Salt la conținutul principal
Română— Alege o limbă
Meniu

Tematică și personalizare

Lecția 18 din 25 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Un singur obiect de opțiuni
  2. Tema
  3. Ecranul de start
  4. Compunătorul
  5. Antet, istoric și răspunsuri
  6. Limba
  7. Punerea cap la cap
  8. Puncte cheie

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/chatkit 1.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 (nu name) pentru sugestiile ecranului de start, și leftAction și rightAction (nu customButtonLeft și customButtonRight) 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țiuneValoriEfect
colorScheme'light', 'dark'Temă deschisă (implicit) sau întunecată
color.accentprimary (hex, rgb(), hsl()…), level de la 0 la 3Culoarea de accent a interfeței și intensitatea paletei
color.grayscalehue în grade, tint de la 0 la 9, shade de la −4 la 4Nuanța și umbra paletei de gri
color.surfacebackground, foregroundCulorile 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ă
typographyfontFamily, fontFamilyMono, baseSize (14 până la 18), fontSourcesFonturi ș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)" },
  • header afișează un titlu fix (altfel titlul curent al firului) și până la două butoane personalizate, leftAction și rightAction, 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ă.
  • history activează 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.feedback afișează butoanele de apreciere (thumbs up/down) sub răspunsuri. Fiecare clic ajunge la serverul dumneavoastră în metoda add_feedback a clasei ChatKitServer (thread_id, item_ids, feedback setat la 'positive' sau 'negative'). Aceasta este materia primă pentru evaluările dumneavoastră. retry adaugă butonul care regenerează un răspuns.
  • disclaimer afiș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 TypeScript
  • startScreen (salut și sugestii), composer (placeholder, instrumente, atașamente), header, history, threadItemActions, disclaimer și locale completează interfața
  • Atașamentele și feedback-ul utilizatorului necesită suport lato-server: uploadStrategy și AttachmentStore, plus metoda add_feedback