Θεματοποίηση και προσαρμογή
Σε αυτήν τη σελίδα
Μάθημα ξαναγραμμένο στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση βασιζόταν σε στοιχεία και επιλογές που δεν υπάρχουν στο ChatKit:
ChatProvider,MessageInput, προσαρμοσμένη απόδοση μηνυμάτων και ενέσιμα φύλλα στυλ. Ακολουθεί πλέον τον οδηγό Θεματοποίηση και προσαρμογή της OpenAI και τους τύπους από το@openai/chatkit1.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.accent | primary (hex, rgb(), hsl()…), level από 0 έως 3 | Χρώμα έμφασης διεπαφής και ένταση παλέτας |
color.grayscale | hue σε μοίρες, tint από 0 έως 9, shade από −4 έως 4 | Απόχρωση και σκίαση της γκρίζας παλέτας |
color.surface | background, foreground | Χρώματα επιφάνειας: φόντο και προσκήνιο (κείμενο, εικονίδια) |
radius | 'pill', 'round', 'soft', 'sharp' | Ακτίνα γωνίας για φυσαλίδες, κουμπιά και πεδία |
density | 'compact', 'normal', 'spacious' | Γενική απόσταση |
typography | fontFamily, 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, με κλειστές τιμές που επικυρώνονται από το TypeScriptstartScreen(χαιρετισμός και προτάσεις),composer(κείμενο κράτησης θέσης, εργαλεία, συνημμένα),header,history,threadItemActions,disclaimerκαιlocaleολοκληρώνουν τη διεπαφή- Τα συνημμένα και τα σχόλια χρηστών απαιτούν υποστήριξη στην πλευρά του διακομιστή:
uploadStrategyκαιAttachmentStore, συν τη μέθοδοadd_feedback