Prilagajanje videza in nastavitev
Na tej strani
Lekcija ponovno napisana 3. novembra 2026. Prejšnja različica se je zanašala na komponente in možnosti, ki v ChatKitu ne obstajajo:
ChatProvider,MessageInput, prilagojeno izrisovanje sporočil in vbrizgane slogovne predloge. Sedaj sledi vodniku OpenAI Theming and customization in tipom iz paketa@openai/chatkit1.9.0; celoten primer je bil preverjen s kompilacijo TypeScript. Dve imeni se razlikujeta med vodnikom in objavljenim paketom, ta lekcija pa sledi paketu:label(nename) za predloge na začetnem zaslonu terleftActioninrightAction(necustomButtonLeftincustomButtonRight) za gumbe v glavi. Viri: Prilagajanje videza v ChatKitu · ReferencaChatKitOptions· ChatKit Studio.
Enoten objekt z možnostmi
Vse prilagoditve ChatKita potekajo prek enotnega objekta z možnostmi. V Reactu ga posredujete funkciji useChatKit({...}); pri spletnem elementu pa metodi chatkit.setOptions({...}). Oblika je v obeh primerih enaka, zato vse, kar se naučite tukaj, velja za vsako integracijo.
Iz arhitekture, obravnavane v prejšnji lekciji, izhaja ena posledica: ChatKit se izriše znotraj iframe, zato vaša slogovna predloga ne more doseči njegove vsebine. Vaša pravila CSS veljajo samo za vsebnik – velikost in položaj, ki ju dodelite elementu <ChatKit className="…" />. Vse ostalo konfigurirate prek možnosti. To je dobra novica za vzdrževanje: posodobitev ChatKita ne more pokvariti selektorjev CSS, ki ne obstajajo.
Če želite možnosti preizkusiti brez pisanja kode, igrišče ChatKit Studio prikaže izris v živo.
Tema
Tema nadzira splošen videz: barvno shemo, poudarjeno barvo, zaobljenost robov, gostoto in tipografijo.
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 },
},
});
Vsaka nastavitev ima zaprt nabor vrednosti, ki jih za vas preveri TypeScript:
| Možnost | Vrednosti | Učinek |
|---|---|---|
colorScheme | 'light', 'dark' | Svetla (privzeto) ali temna tema |
color.accent | primary (hex, rgb(), hsl()…), level od 0 do 3 | Poudarjena barva vmesnika in intenziveta palete |
color.grayscale | hue v stopinjah, tint od 0 do 9, shade od −4 do 4 | Odtenek in senca sive palete |
color.surface | background, foreground | Barve površin: ozadje in ospredje (besedilo, ikone) |
radius | 'pill', 'round', 'soft', 'sharp' | Zaobljenost robov za oblačke, gumbe in polja |
density | 'compact', 'normal', 'spacious' | Splošni razmiki |
typography | fontFamily, fontFamilyMono, baseSize (14 do 18), fontSources | Pisave in osnovna velikost; fontSources naloži spletno pisavo (family, src, weight…) |
Če želite upoštevati uporabnikove nastavitve, izberite shemo ob gradnji možnosti, na primer z window.matchMedia('(prefers-color-scheme: dark)').matches. Sprejeta je tudi tema, reducirana na niz, theme: 'dark', kadar morate nastaviti le barvno shemo.
Začetni zaslon
Prazna nit je lahko zastrašujoča. Začetni zaslon jo nadomesti s pozdravom in predlogi, ki uporabniku pokažejo, kaj asistent zmore:
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 besedilo gumba, prompt je sporočilo, poslano ob kliku uporabnika, icon pa ime s seznama ikon ChatKita (search, write, calendar, lightbulb…) ali ikona Lucide v obliki 'lucide:name'.
Sestavljalec sporočil
Objekt composer konfigurira nadomestno besedilo, orodja, ponujena uporabniku, in priloge:
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'] },
},
},
Orodje, izbrano iz menija, se pošlje strežniku kot nastavitev orodja za naslednji krog; to morate upoštevati v svojem agentu.
Priloge so privzeto onemogočene, njihovo omogočanje pa zahteva delo na strani strežnika. Z lastnim strežnikom morate v api določiti tudi način nalaganja datotek: uploadStrategy: { type: 'direct', uploadUrl: '…' } (vmesnik objavi datoteko na vašo končno točko) ali { type: 'two_phase' } (zahteva podpisani URL, nato pa naloži datoteko v vaše shrambo). Na strani Pythona nato zagotovite AttachmentStore. Dokler ta cevovod ne obstaja, ne obkljukajte enabled: true.
Glava, zgodovina in 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)" },
headerprikaže fiksni naslov (sicer trenutni naslov niti) in do dva prilagojena gumba,leftActioninrightAction, vsak z ikono v glavi (settings-cog,home…) in funkcijo.header: { enabled: false }skrije celotno glavo, ko vaša aplikacija že zagotavlja svojo vrstico.historyomogoči ploščo preteklih pogovorov, z možnostjo preimenovanja in brisanja ali brez. Onemogočite jo, kadar koncept niti za vaš primer uporabe nima smisla, na primer za asistenta za podporo brez uporabniških računov.threadItemActions.feedbackprikaže gumba s palcem gor in dol pod odgovori. Vsak klik prispe na vaš strežnik v metodiadd_feedbackvašegaChatKitServer(thread_id,item_ids,feedbacknastavljen na'positive'ali'negative'). To je surovina za vaša evalvacijo.retrydoda gumb za ponovno generiranje odgovora.disclaimerprikaže kratko besedilo Markdown pod sestavljalcem.
Jezik
ChatKit privzeto uporablja jezik brskalnika. Če ima vaša aplikacija lastno nastavitev jezika, jo vsilite z locale: 'en' ali regionalno različico, kot sta 'en-US' ali 'en-GB'. Vsaka zahteva, poslana vašemu strežniku, nosi ta jezik v glavi Accept-Language: uporabite ga, da agent odgovori in da prevedete sporočila svojih orodij v istem jeziku kot vmesnik.
Vse skupaj
Tukaj je popolna konfiguracija, ki se kot taka kompilira s paketom @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 ugotovitve
- Vse prilagoditve potekajo prek enotnega objekta z možnostmi, ki je enak v Reactu (
useChatKit) in pri spletnem elementu (setOptions) - ChatKit se izriše v iframe: vaš CSS oblikuje le vsebnik; vse ostalo poteka prek
theme theme:colorScheme,color.accent,radius,density,typographyz zaprtimi vrednostmi, ki jih preveri TypeScriptstartScreen(pozdrav in predlogi),composer(nadomestno besedilo, orodja, priloge),header,history,threadItemActions,disclaimerinlocaledopolnjujejo vmesnik- Priloge in uporabniške povratne informacije zahtevajo podporo na strani strežnika:
uploadStrategyinAttachmentStoreter metodaadd_feedback