Témata a přizpůsobení
Na této stránce
Lekce přepsána 3. listopadu 2026. Předchozí verze spoléhala na komponenty a možnosti, které v ChatKitu neexistují:
ChatProvider,MessageInput, vlastní vykreslování zpráv a vkládané styly. Nyní se řídí průvodcem OpenAI Theming and customization a typy z@openai/chatkit1.9.0; kompletní příklad byl ověřen kompilací TypeScriptu. Dva názvy se liší mezi průvodcem a publikovaným balíčkem a tato lekce se řídí balíčkem:label(nikoliname) pro návrhy na úvodní obrazovce aleftActionarightAction(nikolicustomButtonLeftacustomButtonRight) pro tlačítka v záhlaví. Zdroje: Theming and customization in ChatKit ·ChatKitOptionsreference · ChatKit Studio.
Jediný objekt s možnostmi
Veškeré přizpůsobení ChatKitu probíhá prostřednictvím jediného objektu s možnostmi. V Reactu jej předáte funkci useChatKit({...}); u webové komponenty metodě chatkit.setOptions({...}). Struktura je v obou případech totožná, takže vše, co se zde naučíš, platí pro každou integraci.
Z architektury probírané v předchozí lekci vyplývá jeden důsledek: ChatKit se vykresluje uvnitř iframe, takže se k němu nedostane váš stylesheet. Vaše CSS pravidla platí pouze pro kontejner – pro velikost a pozici, kterou přidělíte prvku <ChatKit className="…" />. Vše ostatní se konfiguruje přes možnosti. To je dobrá zpráva pro údržbu: aktualizace ChatKitu nemůže rozbít CSS selektory, které neexistují.
Chcete-li možnosti vyzkoušet bez psaní kódu, ChatKit Studio playground zobrazuje vykreslování v reálném čase.
Téma
Téma řídí celkový vzhled: barevné schéma, akcentní barva, zaoblení rohů, hustota a typografie.
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é nastavení má uzavřenou sadu hodnot, které za vás validuje TypeScript:
| Možnost | Hodnoty | Efekt |
|---|---|---|
colorScheme | 'light', 'dark' | Světlé (výchozí) nebo tmavé téma |
color.accent | primary (hex, rgb(), hsl()…), level od 0 do 3 | Akcentní barva rozhraní a intenzita palety |
color.grayscale | hue ve stupních, tint od 0 do 9, shade od −4 do 4 | Odstín a stín šedé palety |
color.surface | background, foreground | Barvy povrchu: pozadí a popředí (text, ikony) |
radius | 'pill', 'round', 'soft', 'sharp' | Zaoblení rohů pro bubliny, tlačítka a pole |
density | 'compact', 'normal', 'spacious' | Celkové rozestupy |
typography | fontFamily, fontFamilyMono, baseSize (14 až 18), fontSources | Písma a základní velikost; fontSources načítá webové písmo (family, src, weight…) |
Chcete-li respektovat preference uživatele, vyberte schéma při sestavování možností, například pomocí window.matchMedia('(prefers-color-scheme: dark)').matches. Pokud potřebujete nastavit pouze barevné schéma, je přijímán i theme redukovaný na řetězec, tedy theme: 'dark'.
Úvodní obrazovka
Prázdné vlákno může působit zastrašujícím dojmem. Úvodní obrazovka jej nahrazuje pozdravem a návrhy, které uživateli ukážou, co asistent umí:
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čítka, prompt je zpráva odeslaná po kliknutí uživatelem a icon je název ze seznamu ikon ChatKitu (search, write, calendar, lightbulb…), nebo ikona Lucide ve tvaru 'lucide:name'.
Editor zpráv
Objekt composer konfiguruje zástupný text, nástroje nabízené uživateli a pří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 vybraný z nabídky se odešle na server jako preference nástroje pro další krok; musíte s ním počítat ve svém agentovi.
Přílohy jsou ve výchozím nastavení zakázány a jejich povolení vyžaduje práci na straně serveru. S vlastním serverem musíte také v api specifikovat, jak se soubory nahrávají: uploadStrategy: { type: 'direct', uploadUrl: '…' } (rozhraní odešle soubor na váš koncový bod) nebo { type: 'two_phase' } (vyžádá si podepsanou URL, poté nahraje soubor do vašeho úložiště). Na straně Pythonu pak poskytnete AttachmentStore. Nezaškrtávejte enabled: true, dokud tento pipeline neexistuje.
Záhlaví, historie a odpovědi
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ý nadpis (jinak aktuální nadpis vlákna) a až dvě vlastní tlačítka,leftActionarightAction, každé s ikonou v záhlaví (settings-cog,home…) a funkcí.header: { enabled: false }skryje celé záhlaví, pokud vaše aplikace již poskytuje vlastní lištu.historypovoluje panel minulých konverzací, s přejmenováním a mazáním nebo bez nich. Zakažte jej, pokud koncept vlákna pro váš případ použití nedává smysl, například pro asistenta podpory bez uživatelských účtů.threadItemActions.feedbackzobrazuje pod odpověďmi tlačítka s palcem nahoru a dolů. Každé kliknutí dorazí na váš server v metoděadd_feedbackvašehoChatKitServer(thread_id,item_ids,feedbacknastaveno na'positive'nebo'negative'). To je surový materiál pro vaše evaluace.retrypřidá tlačítko pro regeneraci odpovědi.disclaimerzobrazuje krátký text ve formátu Markdown pod editorem zpráv.
Jazyk
ChatKit ve výchozím nastavení používá jazyk prohlížeče. Pokud má vaše aplikace vlastní nastavení jazyka, vynuťte jej pomocí locale: 'en' nebo regionální varianty, jako je 'en-US' nebo 'en-GB'. Každý požadavek odeslaný na váš server nese tento jazyk v hlavičce Accept-Language: využijte jej k tomu, aby agent odpovídal a překládal zprávy vašich nástrojů do stejného jazyka, jako je rozhraní.
Vše dohromady
Zde je kompletní konfigurace, zkompilovaná tak, jak je, s @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" />;
}
Klíčové poznatky
- Veškeré přizpůsobení probíhá prostřednictvím jediného objektu s možnostmi, totožného v Reactu (
useChatKit) i u webové komponenty (setOptions) - ChatKit se vykresluje v iframe: vaše CSS styluje pouze kontejner; vše ostatní jde přes
theme theme:colorScheme,color.accent,radius,density,typographys uzavřenými hodnotami validovanými TypeScriptemstartScreen(pozdrav a návrhy),composer(zástupný text, nástroje, přílohy),header,history,threadItemActions,disclaimeralocaledoplňují rozhraní- Přílohy a zpětná vazba od uživatelů vyžadují podporu na straně serveru:
uploadStrategyaAttachmentStore, plus metoduadd_feedback