Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Témy a prispôsobenie

Lekcia 18 z 25 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Jediný objekt s možnosťami
  2. Téma
  3. Úvodná obrazovka
  4. Editor správ
  5. Hlavička, história a odpovede
  6. Jazyk
  7. Všetko dokopy
  8. Kľúčové poznatky

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/chatkit 1.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 (nie name) pre návrhy na úvodnej obrazovke a leftAction a rightAction (nie customButtonLeft a customButtonRight) pre tlačidlá v hlavičke. Zdroje: Theming and customization in ChatKit · ChatKitOptions reference · 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ťHodnotyEfekt
colorScheme'light', 'dark'Svetlá (predvolená) alebo tmavá téma
color.accentprimary (hex, rgb(), hsl()…), level od 0 do 3Akcentná farba rozhrania a intenzita palety
color.grayscalehue v stupňoch, tint od 0 do 9, shade od −4 do 4Odtieň a tieň šedej palety
color.surfacebackground, foregroundFarby 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
typographyfontFamily, fontFamilyMono, baseSize (14 až 18), fontSourcesPí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)" },
  • header zobrazuje pevný titulok (inak aktuálny titulok vlákna) a až dve vlastné tlačidlá, leftAction a rightAction, každé s ikonou v hlavičke (settings-cog, home…) a funkciou. Nastavenie header: { enabled: false } skryje celú hlavičku, ak tvoja aplikácia už poskytuje vlastný panel.
  • history povoľ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.feedback zobrazuje pod odpoveďami tlačidlá s palcom hore a dole. Každé kliknutie dorazí na tvoj server v metóde add_feedback tvojej triedy ChatKitServer (thread_id, item_ids, feedback nastavené na 'positive' alebo 'negative'). Toto je surový materiál pre tvoje hodnotenia. retry pridáva tlačidlo, ktoré regeneruje odpoveď.
  • disclaimer zobrazuje 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, typography s uzavretými hodnotami validovanými TypeScriptom
  • startScreen (pozdrav a návrhy), composer (zástupný text, nástroje, prílohy), header, history, threadItemActions, disclaimer a locale dokončujú rozhranie
  • Prílohy a spätná väzba od používateľa vyžadujú podporu na strane servera: uploadStrategy a AttachmentStore, plus metódu add_feedback