Teme i prilagodba
Na ovoj stranici
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/chatkit1.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(umjestoname) za prijedloge na početnom zaslonu teleftActionirightAction(umjestocustomButtonLefticustomButtonRight) za gumbe u zaglavlju. Izvori: Teme i prilagodba u ChatKitu · Referenca zaChatKitOptions· 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:
| Opcija | Vrijednosti | Učinak |
|---|---|---|
colorScheme | 'light', 'dark' | Svijetla (zadano) ili tamna tema |
color.accent | primary (hex, rgb(), hsl()…), level od 0 do 3 | Naglasna boja sučelja i intenzitet palete |
color.grayscale | hue u stupnjevima, tint od 0 do 9, shade od −4 do 4 | Nijansa i sjena sive palete |
color.surface | background, foreground | Boje 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 |
typography | fontFamily, fontFamilyMono, baseSize (14 do 18), fontSources | Fontovi 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)" },
headerprikazuje fiksni naslov (inače naslov trenutnog niza) i do dva prilagođena gumba,leftActionirightAction, 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.historyomoguć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.feedbackprikazuje gumbe s palcem gore i dolje ispod odgovora. Svaki klik stiže na tvoj poslužitelj u metodiadd_feedbacktvogChatKitServer(thread_id,item_ids,feedbackpostavljen na'positive'ili'negative'). To je sirovi materijal za tvoje evaluacije.retrydodaje gumb koji ponovno generira odgovor.disclaimerprikazuje 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 TypeScriptstartScreen(pozdrav i prijedlozi),composer(placeholder, alati, privitci),header,history,threadItemActions,disclaimerilocaleupotpunjuju sučelje- Privitci i korisničke povratne informacije zahtijevaju podršku na strani poslužitelja:
uploadStrategyiAttachmentStore, plus metoduadd_feedback