Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Teme i prilagodba

Lekcija 18 od 25 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Jedan objekt s opcijama
  2. Tema
  3. Početni zaslon
  4. Composer (unos)
  5. Zaglavlje, povijest i odgovori
  6. Jezik
  7. Sastavljanje cjeline
  8. Ključne točke

Lekcija je ponovno napisana 3. studenoga 2026. Prethodna verzija oslanjala se na komponente i opcije koje ne postoje u ChatKitu: ChatProvider, MessageInput, prilagođeno renderiranje poruka i umetnute stilove. Sada slijedi OpenAI vodič Theming and customization i tipove iz @openai/chatkit 1.9.0; cjeloviti primjer verificiran je TypeScript kompilacijom. Dva naziva razlikuju se između vodiča i objavljenog paketa, a ova lekcija slijedi paket: label (umjesto name) za prijedloge na početnom zaslonu te leftAction i rightAction (umjesto customButtonLeft i customButtonRight) za gumbe u zaglavlju. Izvori: Teme i prilagodba u ChatKitu · Referenca za ChatKitOptions · ChatKit Studio.

Jedan objekt s opcijama

Sva prilagodba ChatKita odvija se kroz jedan jedini objekt s opcijama. U Reactu ga prosljeđuješ funkciji useChatKit({...}); s web komponentom, metodi chatkit.setOptions({...}). Oblik je u oba slučaja identičan, pa sve što ovdje naučiš vrijedi za svaku integraciju.

Iz arhitekture obrađene u prethodnoj lekciji proizlazi jedna posljedica: ChatKit se renderira unutar iframea, tako da tvoja stilna tablica ne može doprijeti do njega. Tvoja CSS pravila primjenjuju se samo na kontejner — na veličinu i poziciju koju dodijeliš elementu <ChatKit className="…" />. Sve ostalo konfiguriraš putem opcija. To je dobra vijest za održavanje: ažuriranje ChatKita ne može pokvariti CSS selektore koji ne postoje.

Da bi isprobao opcije bez pisanja koda, ChatKit Studio playground prikazuje renderiranje uživo.

Tema

Tema upravlja cjelokupnim izgledom: shemom boja, naglasnom bojom, radijusom kutova, gustoćom i tipografijom.

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 },
  },
});

Svaka postavka ima zatvoren skup vrijednosti koje TypeScript za tebe validira:

OpcijaVrijednostiUčinak
colorScheme'light', 'dark'Svijetla (zadano) ili tamna tema
color.accentprimary (hex, rgb(), hsl()…), level od 0 do 3Naglasna boja sučelja i intenzitet palete
color.grayscalehue u stupnjevima, tint od 0 do 9, shade od −4 do 4Nijansa i sjena sive palete
color.surfacebackground, foregroundBoje površina: pozadina i prednji plan (tekst, ikone)
radius'pill', 'round', 'soft', 'sharp'Radijus kutova za oblačiće, gumbe i polja
density'compact', 'normal', 'spacious'Ukupni razmaci
typographyfontFamily, fontFamilyMono, baseSize (14 do 18), fontSourcesFontovi i osnovna veličina; fontSources učitava web font (family, src, weight…)

Da bi pratio korisnikove postavke, odaberi shemu prilikom izgradnje objekta s opcijama, na primjer pomoću window.matchMedia('(prefers-color-scheme: dark)').matches. Prihvaća se i theme sveden na niz znakova, theme: 'dark', kada trebaš postaviti samo shemu boja.

Početni zaslon

Prazan niz poruka može djelovati zastrašujuće. Početni zaslon zamjenjuje ga pozdravom i prijedlozima koji korisniku pokazuju što asistent može učiniti:

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 tekst gumba, prompt je poruka koja se šalje kada korisnik klikne, a icon je naziv s ChatKitovog popisa ikona (search, write, calendar, lightbulb…) ili Lucide ikona u obliku 'lucide:name'.

Composer (unos)

Objekt composer konfigurira tekst rezerviranog mjesta (placeholder), alate ponuđene korisniku i privitke:

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'] },
  },
},

Alat odabran iz izbornika šalje se poslužitelju kao preferencija alata za sljedeći krug; moraš ga uzeti u obzir u svom agentu.

Privitci su prema zadanim postavkama onemogućeni, a njihovo omogućivanje zahtijeva rad na strani poslužitelja. Sa vlastitim poslužiteljem moraš također u api odrediti kako se datoteke prenose: uploadStrategy: { type: 'direct', uploadUrl: '…' } (sučelje objavljuje datoteku na tvoju krajnju točku) ili { type: 'two_phase' } (zahtijeva potpisani URL, a zatim prenosi datoteku u tvoje spremište). Na strani Pythona tada moraš pružiti AttachmentStore. Ne označavaj enabled: true dok taj pipeline ne postoji.

Zaglavlje, povijest i odgovori

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 prikazuje fiksni naslov (inače naslov trenutnog niza) i do dva prilagođena gumba, leftAction i rightAction, od kojih svaki ima ikonu zaglavlja (settings-cog, home…) i funkciju. header: { enabled: false } skriva cijelo zaglavlje kada tvoja aplikacija već pruža vlastitu traku.
  • history omogućuje ploču prošlih razgovora, s preimenovanjem i brisanjem ili bez njih. Onemogući to kada koncept niza poruka nema smisla za tvoj slučaj upotrebe, na primjer za asistenta za podršku bez korisničkih računa.
  • threadItemActions.feedback prikazuje gumbe s palcem gore i dolje ispod odgovora. Svaki klik stiže na tvoj poslužitelj u metodi add_feedback tvog ChatKitServer (thread_id, item_ids, feedback postavljen na 'positive' ili 'negative'). To je sirovi materijal za tvoje evaluacije. retry dodaje gumb koji ponovno generira odgovor.
  • disclaimer prikazuje kratak Markdown tekst ispod composera.

Jezik

Prema zadanim postavkama, ChatKit koristi jezik preglednika. Ako tvoja aplikacija ima vlastitu postavku jezika, nametni je s locale: 'en' ili regionalnom varijantom poput 'en-US' ili 'en-GB'. Svaki zahtjev poslan tvom poslužitelju nosi ovaj jezik u zaglavlju Accept-Language: iskoristi ga da agent odgovori i da prevedeš poruke svojih alata na isti jezik kao i sučelje.

Sastavljanje cjeline

Evo potpune konfiguracije, kompajlirane kakva jest 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" />;
}

Ključne točke

  • Sva prilagodba odvija se kroz jedan objekt s opcijama, identičan u Reactu (useChatKit) i s web komponentom (setOptions)
  • ChatKit se renderira u iframeu: tvoj CSS stilizira samo kontejner; sve ostalo ide kroz theme
  • theme: colorScheme, color.accent, radius, density, typography, sa zatvorenim vrijednostima koje validira TypeScript
  • startScreen (pozdrav i prijedlozi), composer (placeholder, alati, privitci), header, history, threadItemActions, disclaimer i locale upotpunjuju sučelje
  • Privitci i korisničke povratne informacije zahtijevaju podršku na strani poslužitelja: uploadStrategy i AttachmentStore, plus metodu add_feedback