Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Témata a přizpůsobení

Lekce 18 z 25 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Jediný objekt s možnostmi
  2. Téma
  3. Úvodní obrazovka
  4. Editor zpráv
  5. Záhlaví, historie a odpovědi
  6. Jazyk
  7. Vše dohromady
  8. Klíčové poznatky

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/chatkit 1.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 (nikoli name) pro návrhy na úvodní obrazovce a leftAction a rightAction (nikoli customButtonLeft a customButtonRight) pro tlačítka v záhlaví. Zdroje: Theming and customization in ChatKit · ChatKitOptions reference · 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žnostHodnotyEfekt
colorScheme'light', 'dark'Světlé (výchozí) nebo tmavé téma
color.accentprimary (hex, rgb(), hsl()…), level od 0 do 3Akcentní barva rozhraní a intenzita palety
color.grayscalehue ve stupních, tint od 0 do 9, shade od −4 do 4Odstín a stín šedé palety
color.surfacebackground, foregroundBarvy 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
typographyfontFamily, fontFamilyMono, baseSize (14 až 18), fontSourcesPí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)" },
  • header zobrazuje pevný nadpis (jinak aktuální nadpis vlákna) a až dvě vlastní tlačítka, leftAction a rightAction, 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.
  • history povoluje 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.feedback zobrazuje pod odpověďmi tlačítka s palcem nahoru a dolů. Každé kliknutí dorazí na váš server v metodě add_feedback vašeho ChatKitServer (thread_id, item_ids, feedback nastaveno na 'positive' nebo 'negative'). To je surový materiál pro vaše evaluace. retry přidá tlačítko pro regeneraci odpovědi.
  • disclaimer zobrazuje 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, typography s uzavřenými hodnotami validovanými TypeScriptem
  • startScreen (pozdrav a návrhy), composer (zástupný text, nástroje, přílohy), header, history, threadItemActions, disclaimer a locale doplňují rozhraní
  • Přílohy a zpětná vazba od uživatelů vyžadují podporu na straně serveru: uploadStrategy a AttachmentStore, plus metodu add_feedback