Temaer og tilpasning
På denne side
Lektionen er omskrevet den 3. november 2026. Den tidligere version stolede på komponenter og indstillinger, der ikke findes i ChatKit:
ChatProvider,MessageInput, brugerdefineret meddelelsesvisning og injicerede stylesheets. Den følger nu OpenAI-guiden Theming and customization og typerne fra@openai/chatkit1.9.0; det komplette eksempel er verificeret via TypeScript-kompilering. To navne adskiller sig mellem guiden og den publicerede pakke, og denne lektion følger pakken:label(ikkename) til forslag på startskærmen samtleftActionogrightAction(ikkecustomButtonLeftogcustomButtonRight) til knapper i sidehovedet. Kilder: Theming and customization in ChatKit ·ChatKitOptionsreference · ChatKit Studio.
Et enkelt options-objekt
Al tilpasning af ChatKit sker gennem ét enkelt options-objekt. I React sender du det til useChatKit({...}); med webkomponenten sender du det til chatkit.setOptions({...}). Strukturen er identisk i begge tilfælde, så det du lærer her, gælder for enhver integration.
Én konsekvens følger af arkitekturen fra den foregående lektion: ChatKit renderer inden i en iframe, så dit stylesheet kan ikke nå det. Dine CSS-regler gælder kun for containeren – den størrelse og position, du giver <ChatKit className="…" />. Alt andet konfigureres via options. Dette er gode nyheder for vedligeholdelsen: En opdatering af ChatKit kan ikke ødelægge CSS-selektorer, der ikke eksisterer.
For at prøve options uden at skrive kode viser ChatKit Studio playground renderingen live.
Temaet
Temaet styrer det overordnede udseende: farveskema, accentfarve, hjørneradius, densitet og typografi.
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 },
},
});
Hver indstilling har et lukket sæt af værdier, som TypeScript validerer for dig:
| Option | Værdier | Effekt |
|---|---|---|
colorScheme | 'light', 'dark' | Lyst (standard) eller mørkt tema |
color.accent | primary (hex, rgb(), hsl()…), level fra 0 til 3 | Interface-accentfarve og palettens intensitet |
color.grayscale | hue i grader, tint fra 0 til 9, shade fra −4 til 4 | Nuance og skygge af den grå palette |
color.surface | background, foreground | Overfladefarver: baggrund og forgrund (tekst, ikoner) |
radius | 'pill', 'round', 'soft', 'sharp' | Hjørneradius for bobler, knapper og felter |
density | 'compact', 'normal', 'spacious' | Samlet afstand |
typography | fontFamily, fontFamilyMono, baseSize (14 til 18), fontSources | Skrifttyper og basisstørrelse; fontSources indlæser en webskrifttype (family, src, weight…) |
For at følge brugerens præference vælger du skemaet, når du bygger options, f.eks. med window.matchMedia('(prefers-color-scheme: dark)').matches. Et theme reduceret til en streng, theme: 'dark', accepteres også, når du kun skal angive farveskemaet.
Startskærmen
En tom tråd kan virke skræmmende. Startskærmen erstatter den med en hilsen og forslag, der viser brugeren, hvad assistenten kan gøre:
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 er knapteksten, prompt er beskeden, der sendes, når brugeren klikker, og icon er et navn fra ChatKits ikonliste (search, write, calendar, lightbulb…) eller et Lucide-ikon på formen 'lucide:name'.
Kompositionen
Objektet composer konfigurerer pladsholdertekst, værktøjer tilbudt til brugeren og vedhæftede filer:
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'] },
},
},
Værktøjet valgt fra menuen sendes til serveren som en værktøjspræference for næste tur; du skal tage højde for det i din agent.
Vedhæftede filer er deaktiveret som standard, og aktivering af dem kræver arbejde på serversiden. Med din egen server skal du også angive i api, hvordan filer uploades: uploadStrategy: { type: 'direct', uploadUrl: '…' } (interfacet sender filen til dit endpoint) eller { type: 'two_phase' } (det anmoder om en signeret URL og uploader derefter filen til dit lager). På Python-siden skal du derefter levere en AttachmentStore. Sæt ikke enabled: true, før denne pipeline eksisterer.
Sidehoved, historik og svar
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)" },
headerviser en fast titel (ellers den aktuelle trådtitel) og op til to brugerdefinerede knapper,leftActionogrightAction, hver med et sidehovedsikon (settings-cog,home…) og en funktion.header: { enabled: false }skjuler hele sidehovedet, når din applikation allerede leverer sin egen bjælke.historyaktiverer panelet med tidligere samtaler, med eller uden mulighed for at omdøbe og slette. Deaktivér det, når begrebet en tråd giver ingen mening for dit brugstilfælde, f.eks. for en supportassistent uden brugerkonti.threadItemActions.feedbackviser tommel-op og tommel-ned-knapper under svar. Hvert klik ankommer til din server i metodenadd_feedbacki dinChatKitServer(thread_id,item_ids,feedbacksat til'positive'eller'negative'). Dette er råmaterialet til dine evalueringer.retrytilføjer knappen, der regenererer et svar.disclaimerviser en kort Markdown-tekst under kompositionen.
Sprog
Som standard bruger ChatKit browserens sprog. Hvis din applikation har sin egen sprogindstilling, kan du gennemtvinge den med locale: 'en' eller en regional variant som 'en-US' eller 'en-GB'. Hver anmodning sendt til din server bærer dette sprog i Accept-Language-headere: brug det til at få agenten til at svare og til at oversætte dine værktøjsbeskeder på samme sprog som interfacet.
Samling af det hele
Her er en komplet konfiguration, kompileret som den er med @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" />;
}
Vigtige pointer
- Al tilpasning sker gennem ét enkelt options-objekt, identisk i React (
useChatKit) og med webkomponenten (setOptions) - ChatKit renderer i en iframe: dit CSS styler kun containeren; alt andet går gennem
theme theme:colorScheme,color.accent,radius,density,typography, med lukkede værdier valideret af TypeScriptstartScreen(hilsen og forslag),composer(pladsholder, værktøjer, vedhæftelser),header,history,threadItemActions,disclaimeroglocalefuldender interfacet- Vedhæftede filer og brugerfeedback kræver support på serversiden:
uploadStrategyogAttachmentStoresamt metodenadd_feedback