Tematică și personalizare
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară se baza pe componente și opțiuni care nu există în ChatKit:
ChatProvider,MessageInput, randarea personalizată a mesajelor și foi de stil injectate. Aceasta urmează acum ghidul oficial OpenAI Theming and customization și tipurile din@openai/chatkit1.9.0; exemplul complet a fost verificat prin compilare TypeScript. Două denumiri diferă între ghid și pachetul publicat, iar această lecție respectă pachetul:label(nuname) pentru sugestiile ecranului de start, șileftActionșirightAction(nucustomButtonLeftșicustomButtonRight) pentru butoanele din antet. Surse: Tematică și personalizare în ChatKit · ReferințăChatKitOptions· ChatKit Studio.
Un singur obiect de opțiuni
Toată personalizarea ChatKit se realizează printr-un singur obiect de opțiuni. În React, îl transmiteți funcției useChatKit({...}); cu componenta web, îl transmiteți metodei chatkit.setOptions({...}). Structura este identică în ambele cazuri, astfel încât ceea ce învățați aici se aplică fiecărei integrări.
O consecință decurge din arhitectura prezentată în lecția anterioară: ChatKit se randează într-un iframe, astfel încât foaia dumneavoastră de stil nu îl poate afecta. Regulile CSS se aplică doar containerului — dimensiunea și poziția pe care le atribuiți elementului <ChatKit className="…" />. Tot restul se configurează prin opțiuni. Aceasta este o veste bună pentru mentenanță: o actualizare ChatKit nu poate strica selectori CSS care nu există.
Pentru a testa opțiuni fără a scrie cod, playground-ul ChatKit Studio afișează randarea în timp real.
Tema
Tema controlează aspectul general: schema de culori, culoarea de accent, raza colțurilor, densitatea și tipografia.
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 },
},
});
Fiecare setare are un set închis de valori, pe care TypeScript le validează pentru dumneavoastră:
| Opțiune | Valori | Efect |
|---|---|---|
colorScheme | 'light', 'dark' | Temă deschisă (implicit) sau întunecată |
color.accent | primary (hex, rgb(), hsl()…), level de la 0 la 3 | Culoarea de accent a interfeței și intensitatea paletei |
color.grayscale | hue în grade, tint de la 0 la 9, shade de la −4 la 4 | Nuanța și umbra paletei de gri |
color.surface | background, foreground | Culorile suprafeței: fundal și prim-plan (text, iconițe) |
radius | 'pill', 'round', 'soft', 'sharp' | Raza colțurilor pentru bule, butoane și câmpuri |
density | 'compact', 'normal', 'spacious' | Spațierea generală |
typography | fontFamily, fontFamilyMono, baseSize (14 până la 18), fontSources | Fonturi și dimensiunea de bază; fontSources încarcă un font web (family, src, weight…) |
Pentru a respecta preferința utilizatorului, alegeți schema la construirea opțiunilor, de exemplu cu window.matchMedia('(prefers-color-scheme: dark)').matches. O theme redusă la un șir de caractere, theme: 'dark', este de asemenea acceptată atunci când trebuie doar să setați schema de culori.
Ecranul de start
Un fir de conversație gol poate părea intimidant. Ecranul de start îl înlocuiește cu un salut și sugestii care arată utilizatorului ce poate face asistentul:
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 este textul butonului, prompt este mesajul trimis când utilizatorul dă clic, iar icon este un nume din lista de iconițe ChatKit (search, write, calendar, lightbulb…), sau o iconiță Lucide sub forma 'lucide:name'.
Compunătorul
Obiectul composer configurează textul substituent (placeholder), instrumentele oferite utilizatorului și atașamentele:
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'] },
},
},
Instrumentul selectat din meniu este trimis serverului ca o preferință de instrument pentru următoarea iterație; trebuie să țineți cont de acesta în agentul dumneavoastră.
Atașamentele sunt dezactivate implicit, iar activarea lor necesită lucru lato-server. Cu propriul server, trebuie să specificați și în api modul în care sunt încărcate fișierele: uploadStrategy: { type: 'direct', uploadUrl: '…' } (interfața postează fișierul la endpoint-ul dumneavoastră) sau { type: 'two_phase' } (solicită un URL semnat, apoi încarcă fișierul în stocarea dumneavoastră). În partea de Python, furnizați apoi un AttachmentStore. Nu bifați enabled: true până când acest pipeline nu există.
Antet, istoric și răspunsuri
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)" },
headerafișează un titlu fix (altfel titlul curent al firului) și până la două butoane personalizate,leftActionșirightAction, fiecare cu o iconiță de antet (settings-cog,home…) și o funcție.header: { enabled: false }ascunde întregul antet când aplicația dumneavoastră oferă deja propria bară.historyactivează panoul conversațiilor anterioare, cu sau fără redenumire și ștergere. Dezactivați-l atunci când conceptul de fir de conversație nu are sens pentru cazul dumneavoastră de utilizare, de exemplu pentru un asistent de suport fără conturi de utilizator.threadItemActions.feedbackafișează butoanele de apreciere (thumbs up/down) sub răspunsuri. Fiecare clic ajunge la serverul dumneavoastră în metodaadd_feedbacka claseiChatKitServer(thread_id,item_ids,feedbacksetat la'positive'sau'negative'). Aceasta este materia primă pentru evaluările dumneavoastră.retryadaugă butonul care regenerează un răspuns.disclaimerafișează un scurt text Markdown sub compunător.
Limba
Implicit, ChatKit folosește limba browserului. Dacă aplicația dumneavoastră are propria setare de limbă, impuneți-o cu locale: 'en', sau o variantă regională precum 'en-US' sau 'en-GB'. Fiecare cerere trimisă serverului dumneavoastră poartă această limbă în antetul Accept-Language: folosiți-o pentru a face agentul să răspundă și pentru a traduce mesajele instrumentelor în aceeași limbă cu interfața.
Punerea cap la cap
Iată o configurație completă, compilată ca atare cu @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" />;
}
Puncte cheie
- Toată personalizarea se realizează printr-un singur obiect de opțiuni, identic în React (
useChatKit) și cu componenta web (setOptions) - ChatKit se randează într-un iframe: CSS-ul dumneavoastră stilează doar containerul; tot restul trece prin
theme theme:colorScheme,color.accent,radius,density,typography, cu valori închise validate de TypeScriptstartScreen(salut și sugestii),composer(placeholder, instrumente, atașamente),header,history,threadItemActions,disclaimerșilocalecompletează interfața- Atașamentele și feedback-ul utilizatorului necesită suport lato-server:
uploadStrategyșiAttachmentStore, plus metodaadd_feedback