Teman och anpassning
På denna sida
Lektionen omskriven den 3 november 2026. Den tidigare versionen förlitade sig på komponenter och alternativ som inte finns i ChatKit:
ChatProvider,MessageInput, anpassad meddelanderendering och injicerade stilmallar. Den följer nu OpenAIs guide Theming and customization och typerna från@openai/chatkit1.9.0; hela exemplet har verifierats via TypeScript-kompilering. Två namn skiljer sig mellan guiden och det publicerade paketet, och denna lektion följer paketet:label(intename) för förslag på startskärmen, samtleftActionochrightAction(intecustomButtonLeftochcustomButtonRight) för knappar i sidhuvudet. Källor: Theming and customization in ChatKit ·ChatKitOptions-referens · ChatKit Studio.
Ett enda optionsobjekt
All anpassning av ChatKit sker genom ett enda optionsobjekt. I React skickar du det till useChatKit({...}); med webbkompontenten skickar du det till chatkit.setOptions({...}). Strukturen är identisk i båda fallen, så det du lär dig här gäller för varje integration.
En konsekvens följer av arkitekturen som täcktes i föregående lektion: ChatKit renderar inuti en iframe, så din stilmall når inte dit. Dina CSS-regler gäller endast för containern – storleken och positionen du ger <ChatKit className="…" />. Allt annat konfigureras via options. Detta är goda nyheter för underhållet: en uppdatering av ChatKit kan inte bryta CSS-selektorer som inte finns.
För att testa options utan att skriva kod visar ChatKit Studio playground rendering i realtid.
Temat
Temat styr det övergripande utseendet: färgschema, accentfärg, hörnradie, densitet och 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 },
},
});
Varje inställning har en sluten uppsättning värden, vilket TypeScript validerar åt dig:
| Alternativ | Värden | Effekt |
|---|---|---|
colorScheme | 'light', 'dark' | Ljust (standard) eller mörkt tema |
color.accent | primary (hex, rgb(), hsl()…), level från 0 till 3 | Gränssnittets accentfärg och palettens intensitet |
color.grayscale | hue i grader, tint från 0 till 9, shade från −4 till 4 | Nyans och skugga för den grå paletten |
color.surface | background, foreground | Ytfärger: bakgrund och förgrund (text, ikoner) |
radius | 'pill', 'round', 'soft', 'sharp' | Hörnradie för bubblor, knappar och fält |
density | 'compact', 'normal', 'spacious' | Övergripande avstånd |
typography | fontFamily, fontFamilyMono, baseSize (14 till 18), fontSources | Typsnitt och basstorlek; fontSources laddar ett webbtypsnitt (family, src, weight…) |
För att följa användarens preferens, välj schemat när du bygger options, till exempel med window.matchMedia('(prefers-color-scheme: dark)').matches. Ett theme reducerat till en sträng, theme: 'dark', accepteras också när du bara behöver ställa in färgschemat.
Startskärmen
En tom tråd kan kännas skrämmande. Startskärmen ersätter den med en hälsning och förslag som visar användaren vad assistenten kan göra:
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 är knapptexten, prompt är meddelandet som skickas när användaren klickar, och icon är ett namn från ChatKits ikonlista (search, write, calendar, lightbulb…), eller en Lucide-ikon på formen 'lucide:name'.
Kompositören
Objektet composer konfigurerar platshållartext, verktyg som erbjuds användaren och bilagor:
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 fil
accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
},
},
Verktyget som väljs från menyn skickas till servern som en verktygspreferens för nästa tur; du måste ta hänsyn till detta i din agent.
Bilagor är inaktiverade som standard, och att aktivera dem kräver arbete på serversidan. Med din egen server måste du också ange i api hur filer laddas upp: uploadStrategy: { type: 'direct', uploadUrl: '…' } (gränssnittet postar filen till din endpoint) eller { type: 'two_phase' } (det begär en signerad URL och laddar sedan upp filen till ditt lagring). På Python-sidan tillhandahåller du sedan en AttachmentStore. Kryssa inte i enabled: true förrän denna pipeline finns.
Sidhuvud, historik och 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)" },
headervisar en fast titel (annars den aktuella trådtiteln) och upp till två anpassade knappar,leftActionochrightAction, var och en med en sidhuvudsikon (settings-cog,home…) och en funktion.header: { enabled: false }döljer hela sidhuvudet när din applikation redan tillhandahåller sin egen menylist.historyaktiverar panelen för tidigare konversationer, med eller utan möjlighet att byta namn och radera. Inaktivera detta när begreppet tråd inte ger mening för ditt användningsfall, till exempel för en supportassistent utan användarkonton.threadItemActions.feedbackvisar tumme upp- och tumme ner-knappar under svar. Varje klick når din server i metodenadd_feedbacki dinChatKitServer(thread_id,item_ids,feedbacksatt till'positive'eller'negative'). Detta är råmaterialet för dina utvärderingar.retrylägger till knappen som genererar om ett svar.disclaimervisar en kort Markdown-text under kompositören.
Språk
Som standard använder ChatKit webbläsarens språk. Om din applikation har sin egen språkinställning, tvinga fram den med locale: 'en', eller en regional variant som 'en-US' eller 'en-GB'. Varje begäran som skickas till din server bär med sig detta språk i headern Accept-Language: använd det för att få agenten att svara och för att översätta dina verktygsmeddelanden till samma språk som gränssnittet.
Sätta ihop allt
Här är en komplett konfiguration, kompilerad i befintligt skick 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" />;
}
Viktiga punkter
- All anpassning sker genom ett enda optionsobjekt, identiskt i React (
useChatKit) och med webbkompontenten (setOptions) - ChatKit renderar i en iframe: din CSS stylar endast containern; allt annat går via
theme theme:colorScheme,color.accent,radius,density,typography, med slutna värden validerade av TypeScriptstartScreen(hälsning och förslag),composer(platshållare, verktyg, bilagor),header,history,threadItemActions,disclaimerochlocalekompletterar gränssnittet- Bilagor och användarfeedback kräver stöd på serversidan:
uploadStrategyochAttachmentStore, plus metodenadd_feedback