Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Θεματοποίηση και προσαρμογή

Μάθημα 18 / 25 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Ένα μοναδικό αντικείμενο επιλογών
  2. Το θέμα
  3. Η αρχική οθόνη
  4. Ο συνθέτης
  5. Κεφαλίδα, ιστορικό και απαντήσεις
  6. Γλώσσα
  7. Συγκεντρώνοντας τα πάντα
  8. Βασικά σημεία

Μάθημα ξαναγραμμένο στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση βασιζόταν σε στοιχεία και επιλογές που δεν υπάρχουν στο ChatKit: ChatProvider, MessageInput, προσαρμοσμένη απόδοση μηνυμάτων και ενέσιμα φύλλα στυλ. Ακολουθεί πλέον τον οδηγό Θεματοποίηση και προσαρμογή της OpenAI και τους τύπους από το @openai/chatkit 1.9.0· το πλήρες παράδειγμα έχει επαληθευτεί μέσω μεταγλώττισης TypeScript. Δύο ονόματα διαφέρουν μεταξύ του οδηγού και του δημοσιευμένου πακέτου, και αυτό το μάθημα ακολουθεί το πακέτο: label (όχι name) για τις προτάσεις της αρχικής οθόνης, και leftAction και rightAction (όχι customButtonLeft και customButtonRight) για τα κουμπιά της κεφαλίδας. Πηγές: Θεματοποίηση και προσαρμογή στο ChatKit · Αναφορά ChatKitOptions · ChatKit Studio.

Ένα μοναδικό αντικείμενο επιλογών

Όλη η προσαρμογή του ChatKit γίνεται μέσω ενός μοναδικού αντικειμένου επιλογών. Στο React, το περνάτε στο useChatKit({...})· με το web component, στο chatkit.setOptions({...}). Η δομή είναι ίδια και στις δύο περιπτώσεις, οπότε ό,τι μάθετε εδώ ισχύει για κάθε ενσωμάτωση.

Μια συνέπεια προκύπτει από την αρχιτεκτονική που καλύφθηκε στο προηγούμενο μάθημα: το ChatKit αποδίδεται μέσα σε ένα iframe, επομένως το φύλλο στυλ σας δεν μπορεί να το προσεγγίσει. Οι κανόνες CSS σας εφαρμόζονται μόνο στο container—στο μέγεθος και τη θέση που δίνετε στο <ChatKit className="…" />. Όλα τα υπόλοιπα ρυθμίζονται μέσω επιλογών. Αυτό είναι καλά νέα για τη συντήρηση: μια ενημέρωση του ChatKit δεν μπορεί να σπάσει επιλογείς CSS που δεν υπάρχουν.

Για να δοκιμάσετε επιλογές χωρίς να γράψετε κώδικα, το ChatKit Studio playground εμφανίζει την απόδοση σε πραγματικό χρόνο.

Το θέμα

Το θέμα ελέγχει τη γενική εμφάνιση: χρωματικό σχήμα, χρώμα έμφασης, ακτίνα γωνίας, πυκνότητα και τυπογραφία.

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  theme: {
    colorScheme: 'dark',
    color: {
      accent: { primary: '#2D8CFF', level: 2 },
    },
    radius: 'round',
    density: 'compact',
    typography: { fontFamily: "'Inter', sans-serif", baseSize: 16 },
  },
});

Κάθε ρύθμιση έχει ένα κλειστό σύνολο τιμών, τις οποίες το TypeScript επικυρώνει για εσάς:

ΕπιλογήΤιμέςΕπίδραση
colorScheme'light', 'dark'Ανοιχτό (προεπιλογή) ή σκούρο θέμα
color.accentprimary (hex, rgb(), hsl()…), level από 0 έως 3Χρώμα έμφασης διεπαφής και ένταση παλέτας
color.grayscalehue σε μοίρες, tint από 0 έως 9, shade από −4 έως 4Απόχρωση και σκίαση της γκρίζας παλέτας
color.surfacebackground, foregroundΧρώματα επιφάνειας: φόντο και προσκήνιο (κείμενο, εικονίδια)
radius'pill', 'round', 'soft', 'sharp'Ακτίνα γωνίας για φυσαλίδες, κουμπιά και πεδία
density'compact', 'normal', 'spacious'Γενική απόσταση
typographyfontFamily, fontFamilyMono, baseSize (14 έως 18), fontSourcesΓραμματοσειρές και βασικό μέγεθος· το fontSources φορτώνει μια γραμματοσειρά web (family, src, weight…)

Για να ακολουθήσετε την προτίμηση του χρήστη, επιλέξτε το σχήμα κατά τη δημιουργία των επιλογών, για παράδειγμα με window.matchMedia('(prefers-color-scheme: dark)').matches. Ένα theme μειωμένο σε συμβολοσειρά, theme: 'dark', γίνεται επίσης δεκτό όταν χρειάζεται να ορίσετε μόνο το χρωματικό σχήμα.

Η αρχική οθόνη

Ένα κενό νήμα μπορεί να φαίνεται εκφοβιστικό. Η αρχική οθόνη το αντικαθιστά με έναν χαιρετισμό και προτάσεις που δείχνουν στον χρήστη τι μπορεί να κάνει ο βοηθός:

startScreen: {
  greeting: 'Hello! How can I help you?',
  prompts: [
    { label: 'Track an order', prompt: 'Where is my latest order?', icon: 'search' },
    { label: 'Open a ticket', prompt: 'I would like to report an issue.', icon: 'write' },
  ],
},

Το label είναι το κείμενο του κουμπιού, το prompt είναι το μήνυμα που στέλνεται όταν ο χρήστης κάνει κλικ, και το icon είναι ένα όνομα από τη λίστα εικονιδίων του ChatKit (search, write, calendar, lightbulb…), ή ένα εικονίδιο Lucide στη μορφή 'lucide:name'.

Ο συνθέτης

Το αντικείμενο composer διαμορφώνει το κείμενο κράτησης θέσης, τα εργαλεία που προσφέρονται στον χρήστη και τα συνημμένα:

composer: {
  placeholder: 'Ask a question about your order…',
  tools: [
    { id: 'order-search', label: 'Search order', icon: 'search', pinned: true },
  ],
  attachments: {
    enabled: true,
    maxCount: 3,
    maxSize: 20 * 1024 * 1024, // 20 MB per file
    accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
  },
},

Το εργαλείο που επιλέγεται από το μενού στέλνεται στον διακομιστή ως προτίμηση εργαλείου για τον επόμενο γύρο· πρέπει να το λάβετε υπόψη στον πράκτορά σας.

Τα συνημμένα είναι απενεργοποιημένα από προεπιλογή και η ενεργοποίησή τους απαιτεί εργασία στην πλευρά του διακομιστή. Με τον δικό σας διακομιστή, πρέπει επίσης να καθορίσετε στο api πώς μεταφορτώνονται τα αρχεία: uploadStrategy: { type: 'direct', uploadUrl: '…' } (η διεπαφή αναρτά το αρχείο στο endpoint σας) ή { type: 'two_phase' } (ζητά μια υπογεγραμμένη URL και στη συνέχεια ανεβάζει το αρχείο στον αποθηκευτικό σας χώρο). Στην πλευρά της Python, παρέχετε τότε ένα AttachmentStore. Μην ελέγξετε το enabled: true έως ότου υπάρχει αυτή η ροή εργασίας.

Κεφαλίδα, ιστορικό και απαντήσεις

header: {
  title: { text: 'Order Assistant' },
  leftAction: { icon: 'settings-cog', onClick: () => openSettings() },
},
history: { enabled: true, showRename: true, showDelete: false },
threadItemActions: { feedback: true, retry: true },
disclaimer: { text: "Responses may contain errors. [Our terms](/terms)" },
  • Το header εμφανίζει έναν σταθερό τίτλο (διαφορετικά τον τρέχοντα τίτλο του νήματος) και έως δύο προσαρμοσμένα κουμπιά, leftAction και rightAction, το καθένα με ένα εικονίδιο κεφαλίδας (settings-cog, home…) και μια συνάρτηση. Το header: { enabled: false } κρύβει ολόκληρη την κεφαλίδα όταν η εφαρμογή σας παρέχει ήδη τη δική της μπάρα.
  • Το history ενεργοποιεί τον πίνακα προηγούμενων συνομιλιών, με ή χωρίς μετονομασία και διαγραφή. Απενεργοποιήστε το όταν η έννοια του νήματος δεν έχει νόημα για την περίπτωσή σας, για παράδειγμα για έναν βοηθό υποστήριξης χωρίς λογαριασμούς χρηστών.
  • Το threadItemActions.feedback εμφανίζει κουμπιά «μου αρέσει» και «δεν μου αρέσει» κάτω από τις απαντήσεις. Κάθε κλικ φτάνει στον διακομιστή σας στη μέθοδο add_feedback του ChatKitServer σας (thread_id, item_ids, feedback ορισμένο σε 'positive' ή 'negative'). Αυτό είναι η πρώτη ύλη για τις αξιολογήσεις σας. Το retry προσθέτει το κουμπί που αναπαράγει μια απάντηση.
  • Το disclaimer εμφανίζει ένα σύντομο κείμενο Markdown κάτω από τον συνθέτη.

Γλώσσα

Από προεπιλογή, το ChatKit χρησιμοποιεί τη γλώσσα του προγράμματος περιήγησης. Εάν η εφαρμογή σας έχει τη δική της ρύθμιση γλώσσας, επιβάλετέ την με locale: 'en', ή μια περιφερειακή παραλλαγή όπως 'en-US' ή 'en-GB'. Κάθε αίτημα που στέλνεται στον διακομιστή σας μεταφέρει αυτή τη γλώσσα στην κεφαλίδα Accept-Language: χρησιμοποιήστε την για να κάνετε τον πράκτορα να απαντήσει και να μεταφράσετε τα μηνύματα των εργαλείων σας στην ίδια γλώσσα με τη διεπαφή.

Συγκεντρώνοντας τα πάντα

Εδώ είναι μια πλήρης διαμόρφωση, μεταγλωττισμένη ως έχει με το @openai/chatkit-react 1.6.1:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function OrderAssistant({ openSettings }: { openSettings: () => void }) {
  const dark = window.matchMedia('(prefers-color-scheme: dark)').matches;

  const { control } = useChatKit({
    api: { url: '/chatkit', domainKey: 'local-dev' },
    locale: 'en',
    theme: {
      colorScheme: dark ? 'dark' : 'light',
      color: { accent: { primary: '#2D8CFF', level: 2 } },
      radius: 'round',
      density: 'normal',
    },
    startScreen: {
      greeting: 'Hello! How can I help you?',
      prompts: [
        { label: 'Track an order', prompt: 'Where is my latest order?', icon: 'search' },
        { label: 'Open a ticket', prompt: 'I would like to report an issue.', icon: 'write' },
      ],
    },
    composer: { placeholder: 'Ask a question about your order…' },
    header: {
      title: { text: 'Order Assistant' },
      leftAction: { icon: 'settings-cog', onClick: openSettings },
    },
    history: { enabled: true, showRename: true, showDelete: false },
    threadItemActions: { feedback: true, retry: true },
  });

  return <ChatKit control={control} className="h-[640px] w-full max-w-md" />;
}

Βασικά σημεία

  • Όλη η προσαρμογή γίνεται μέσω ενός μοναδικού αντικειμένου επιλογών, ίδιο στο React (useChatKit) και με το web component (setOptions)
  • Το ChatKit αποδίδεται σε iframe: το CSS σας στυλάρει μόνο το container· όλα τα υπόλοιπα περνούν μέσω του theme
  • theme: colorScheme, color.accent, radius, density, typography, με κλειστές τιμές που επικυρώνονται από το TypeScript
  • startScreen (χαιρετισμός και προτάσεις), composer (κείμενο κράτησης θέσης, εργαλεία, συνημμένα), header, history, threadItemActions, disclaimer και locale ολοκληρώνουν τη διεπαφή
  • Τα συνημμένα και τα σχόλια χρηστών απαιτούν υποστήριξη στην πλευρά του διακομιστή: uploadStrategy και AttachmentStore, συν τη μέθοδο add_feedback