Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Temaer og tilpasning

Lektion 18 af 25 Opdateret 3. november 2026 Udvikler
På denne side
  1. Et enkelt options-objekt
  2. Temaet
  3. Startskærmen
  4. Kompositionen
  5. Sidehoved, historik og svar
  6. Sprog
  7. Samling af det hele
  8. Vigtige pointer

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/chatkit 1.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 (ikke name) til forslag på startskærmen samt leftAction og rightAction (ikke customButtonLeft og customButtonRight) til knapper i sidehovedet. Kilder: Theming and customization in ChatKit · ChatKitOptions reference · 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:

OptionVærdierEffekt
colorScheme'light', 'dark'Lyst (standard) eller mørkt tema
color.accentprimary (hex, rgb(), hsl()…), level fra 0 til 3Interface-accentfarve og palettens intensitet
color.grayscalehue i grader, tint fra 0 til 9, shade fra −4 til 4Nuance og skygge af den grå palette
color.surfacebackground, foregroundOverfladefarver: baggrund og forgrund (tekst, ikoner)
radius'pill', 'round', 'soft', 'sharp'Hjørneradius for bobler, knapper og felter
density'compact', 'normal', 'spacious'Samlet afstand
typographyfontFamily, fontFamilyMono, baseSize (14 til 18), fontSourcesSkrifttyper 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)" },
  • header viser en fast titel (ellers den aktuelle trådtitel) og op til to brugerdefinerede knapper, leftAction og rightAction, 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.
  • history aktiverer 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.feedback viser tommel-op og tommel-ned-knapper under svar. Hvert klik ankommer til din server i metoden add_feedback i din ChatKitServer (thread_id, item_ids, feedback sat til 'positive' eller 'negative'). Dette er råmaterialet til dine evalueringer. retry tilføjer knappen, der regenererer et svar.
  • disclaimer viser 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 TypeScript
  • startScreen (hilsen og forslag), composer (pladsholder, værktøjer, vedhæftelser), header, history, threadItemActions, disclaimer og locale fuldender interfacet
  • Vedhæftede filer og brugerfeedback kræver support på serversiden: uploadStrategy og AttachmentStore samt metoden add_feedback