Témy a prispôsobenie
Na tejto strane
Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia sa spoliehala na komponenty a možnosti, ktoré v ChatKite neexistujú:
ChatProvider,MessageInput, vlastné vykresľovanie správ a vstrekované štýly. Teraz nasleduje príručku OpenAI Theming and customization a typy z balíka@openai/chatkit1.9.0; kompletný príklad bol overený kompiláciou TypeScriptu. Dva názvy sa líšia medzi príručkou a publikovaným balíkom a táto lekcia sa riadi balíkom:label(niename) pre návrhy na úvodnej obrazovke aleftActionarightAction(niecustomButtonLeftacustomButtonRight) pre tlačidlá v hlavičke. Zdroje: Theming and customization in ChatKit ·ChatKitOptionsreference · ChatKit Studio.
Jediný objekt s možnosťami
Všetky prispôsobenia ChatKitu prebiehajú prostredníctvom jediného objektu s možnosťami. V Reacte ho odovzdáš funkcii useChatKit({...}); pri webovom komponente funkcii chatkit.setOptions({...}). Štruktúra je v oboch prípadoch identická, takže všetko, čo sa tu naučíš, platí pre každú integráciu.
Z architektúry pokrytej v predchádzajúcej lekcii vyplýva jeden dôsledok: ChatKit sa vykresľuje vo vnútri iframe, takže sa doňho nedostane tvoj štýlový súbor. Tvoje pravidlá CSS sa vzťahujú len na kontajner – na veľkosť a pozíciu, ktorú pridelíš prvku <ChatKit className="…" />. Všetko ostatné sa konfiguruje cez možnosti. To je dobrá správa pre údržbu: aktualizácia ChatKitu nemôže rozbiť selektory CSS, ktoré neexistujú.
Ak chceš možnosti vyskúšať bez písania kódu, ChatKit Studio playground zobrazuje vykresľovanie v reálnom čase.
Téma
Téma riadi celkový vzhľad: farebnú schému, akcentnú farbu, zaoblenie rohov, hustotu a typografiu.
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 },
},
});
Každé nastavenie má uzavretú množinu hodnôt, ktorú za teba validuje TypeScript:
| Možnosť | Hodnoty | Efekt |
|---|---|---|
colorScheme | 'light', 'dark' | Svetlá (predvolená) alebo tmavá téma |
color.accent | primary (hex, rgb(), hsl()…), level od 0 do 3 | Akcentná farba rozhrania a intenzita palety |
color.grayscale | hue v stupňoch, tint od 0 do 9, shade od −4 do 4 | Odtieň a tieň šedej palety |
color.surface | background, foreground | Farby povrchu: pozadie a popredie (text, ikony) |
radius | 'pill', 'round', 'soft', 'sharp' | Zaoblenie rohov pre bubliny, tlačidlá a polia |
density | 'compact', 'normal', 'spacious' | Celkové rozostupy |
typography | fontFamily, fontFamilyMono, baseSize (14 až 18), fontSources | Písma a základná veľkosť; fontSources načíta webový font (family, src, weight…) |
Ak chceš nasledovať preferencie používateľa, vyber schému pri zostavovaní možností, napríklad pomocou window.matchMedia('(prefers-color-scheme: dark)').matches. Ak potrebuješ nastaviť len farebnú schému, akceptuje sa aj theme zredukovaný na reťazec, teda theme: 'dark'.
Úvodná obrazovka
Prázdne vlákno môže pôsobiť zastrašujúco. Úvodná obrazovka ho nahradí pozdravom a návrhmi, ktoré používateľovi ukážu, čo asistent dokáže:
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 je text tlačidla, prompt je správa odoslaná po kliknutí používateľa a icon je názov zo zoznamu ikon ChatKitu (search, write, calendar, lightbulb…) alebo ikona Lucide v tvare 'lucide:name'.
Editor správ
Objekt composer konfiguruje zástupný text, nástroje ponúkané používateľovi a prílohy:
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'] },
},
},
Nástroj vybratý z ponuky sa odosiela na server ako preferencia nástroja pre ďalší krok; musíš s ním počítať vo svojom agentovi.
Prílohy sú predvolene vypnuté a ich povolenie si vyžaduje prácu na strane servera. Pri vlastnom serveri musíš v časti api tiež špecifikovať, ako sa súbory nahrávajú: uploadStrategy: { type: 'direct', uploadUrl: '…' } (rozhranie odošle súbor na tvoj koncový bod) alebo { type: 'two_phase' } (vyžiada si podpísanú URL a potom nahrá súbor do tvojho úložiska). Na strane Pythonu potom poskytnes AttachmentStore. Nezaškrtávaj enabled: true, kým tento pipeline neexistuje.
Hlavička, história a odpovede
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)" },
headerzobrazuje pevný titulok (inak aktuálny titulok vlákna) a až dve vlastné tlačidlá,leftActionarightAction, každé s ikonou v hlavičke (settings-cog,home…) a funkciou. Nastavenieheader: { enabled: false }skryje celú hlavičku, ak tvoja aplikácia už poskytuje vlastný panel.historypovoľuje panel minulých konverzácií, s premenovaním a vymazaním alebo bez nich. Vypni ho, ak koncept vlákna nedáva zmysel pre tvoj prípad použitia, napríklad pri asistentovi podpory bez používateľských účtov.threadItemActions.feedbackzobrazuje pod odpoveďami tlačidlá s palcom hore a dole. Každé kliknutie dorazí na tvoj server v metódeadd_feedbacktvojej triedyChatKitServer(thread_id,item_ids,feedbacknastavené na'positive'alebo'negative'). Toto je surový materiál pre tvoje hodnotenia.retrypridáva tlačidlo, ktoré regeneruje odpoveď.disclaimerzobrazuje krátky text vo formáte Markdown pod editorom správ.
Jazyk
ChatKit predvolene používa jazyk prehliadača. Ak má tvoja aplikácia vlastné nastavenie jazyka, vynúť ho pomocou locale: 'en' alebo regionálneho variantu ako 'en-US' či 'en-GB'. Každá požiadavka odoslaná na tvoj server nesie tento jazyk v hlavičke Accept-Language: využiji ho na to, aby agent odpovedal a aby si preložil správy svojich nástrojov do rovnakého jazyka, aký používa rozhranie.
Všetko dokopy
Tu je kompletná konfigurácia, skompilovaná tak, ako je, s balíkom @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" />;
}
Kľúčové poznatky
- Všetky prispôsobenia prebiehajú prostredníctvom jediného objektu s možnosťami, ktorý je identický v Reacte (
useChatKit) aj pri webovom komponente (setOptions) - ChatKit sa vykresľuje v iframe: tvoje CSS štýluje len kontajner; všetko ostatné ide cez
theme theme:colorScheme,color.accent,radius,density,typographys uzavretými hodnotami validovanými TypeScriptomstartScreen(pozdrav a návrhy),composer(zástupný text, nástroje, prílohy),header,history,threadItemActions,disclaimeralocaledokončujú rozhranie- Prílohy a spätná väzba od používateľa vyžadujú podporu na strane servera:
uploadStrategyaAttachmentStore, plus metóduadd_feedback