Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Theming und Anpassung

Lektion 18 von 25 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Ein einziges Options-Objekt
  2. Das Theme
  3. Der Startbildschirm
  4. Der Komponist
  5. Header, Verlauf und Antworten
  6. Sprache
  7. Alles zusammengefasst
  8. Wichtige Erkenntnisse

Lektion am 3. November 2026 überarbeitet. Die vorherige Version stützte sich auf Komponenten und Optionen, die in ChatKit nicht existieren: ChatProvider, MessageInput, benutzerdefiniertes Nachrichtenrendering und injizierte Stylesheets. Sie folgt nun dem OpenAI-Leitfaden zu Theming und Anpassung sowie den Typen aus @openai/chatkit 1.9.0; das vollständige Beispiel wurde über die TypeScript-Kompilierung verifiziert. Zwei Namen unterscheiden sich zwischen dem Leitfaden und dem veröffentlichten Paket, und diese Lektion folgt dem Paket: label (nicht name) für Vorschläge auf dem Startbildschirm und leftAction sowie rightAction (nicht customButtonLeft und customButtonRight) für Header-Buttons. Quellen: Theming und Anpassung in ChatKit · ChatKitOptions-Referenz · ChatKit Studio.

Ein einziges Options-Objekt

Alle Anpassungen an ChatKit erfolgen über ein einziges Options-Objekt. In React übergeben Sie es an useChatKit({...}); bei dem Web-Komponenten an chatkit.setOptions({...}). Die Struktur ist in beiden Fällen identisch, sodass das, was Sie hier lernen, auf jede Integration anwendbar ist.

Eine Konsequenz ergibt sich aus der Architektur der vorherigen Lektion: ChatKit renderisiert innerhalb eines Iframes, sodass Ihre Stylesheet-Regeln ihn nicht erreichen können. Ihre CSS-Regeln gelten nur für den Container – die Größe und Position, die Sie <ChatKit className="…" /> geben. Alles andere wird über Optionen konfiguriert. Das ist gute Nachrichten für die Wartung: Ein Update von ChatKit kann CSS-Selektoren nicht brechen, die nicht existieren.

Um Optionen ohne Code zu testen, zeigt der ChatKit Studio Playground eine Live-Vorschau.

Das Theme

Das Theme steuert das Gesamterscheinungsbild: Farbschema, Akzentfarbe, Eckenradius, Dichte und Typografie.

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 },
  },
});

Jede Einstellung verfügt über einen geschlossenen Satz von Werten, die TypeScript für Sie validiert:

OptionWerteWirkung
colorScheme'light', 'dark'Helles (Standard) oder dunkles Theme
color.accentprimary (Hex, rgb(), hsl()…), level von 0 bis 3Akzentfarbe der Benutzeroberfläche und Intensität der Farbpalette
color.grayscalehue in Grad, tint von 0 bis 9, shade von −4 bis 4Farbton und Schattierung der Graupalette
color.surfacebackground, foregroundOberflächenfarben: Hintergrund und Vordergrund (Text, Symbole)
radius'pill', 'round', 'soft', 'sharp'Eckenradius für Blasen, Buttons und Felder
density'compact', 'normal', 'spacious'Gesamtabstände
typographyfontFamily, fontFamilyMono, baseSize (14 bis 18), fontSourcesSchriftarten und Grundgröße; fontSources lädt eine Web-Schriftart (family, src, weight…)

Um die Präferenz des Benutzers zu berücksichtigen, wählen Sie das Schema beim Erstellen der Optionen, beispielsweise mit window.matchMedia('(prefers-color-scheme: dark)').matches. Ein theme, das auf einen String reduziert ist, theme: 'dark', wird ebenfalls akzeptiert, wenn Sie nur das Farbschema festlegen möchten.

Der Startbildschirm

Ein leerer Thread kann einschüchternd wirken. Der Startbildschirm ersetzt ihn durch eine Begrüßung und Vorschläge, die dem Benutzer zeigen, was der Assistent kann:

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 ist der Button-Text, prompt ist die gesendete Nachricht, wenn der Benutzer klickt, und icon ist ein Name aus der ChatKit-Symbolliste (search, write, calendar, lightbulb…), oder ein Lucide-Symbol in der Form 'lucide:name'.

Der Komponist

Das composer-Objekt konfiguriert den Platzhaltertext, die dem Benutzer angebotenen Werkzeuge und Anhänge:

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 pro Datei
    accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
  },
},

Das vom Menü ausgewählte Werkzeug wird dem Server als Werkzeugpräferenz für die nächste Runde gesendet; Sie müssen dies in Ihrem Agenten berücksichtigen.

Anhänge sind standardmäßig deaktiviert, und ihre Aktivierung erfordert Server-seitige Arbeit. Mit Ihrem eigenen Server müssen Sie auch in api angeben, wie Dateien hochgeladen werden: uploadStrategy: { type: 'direct', uploadUrl: '…' } (das Interface sendet die Datei an Ihren Endpunkt) oder { type: 'two_phase' } (es fordert eine signierte URL an, und die Datei wird dann in Ihre Speicherlösung hochgeladen). Auf der Python-Seite stellen Sie dann einen AttachmentStore bereit. Prüfen Sie enabled: true nicht, bevor diese Pipeline existiert.

Header, Verlauf und Antworten

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 zeigt einen festen Titel (sonst den Titel des aktuellen Threads) und bis zu zwei benutzerdefinierte Buttons, leftAction und rightAction, jeweils mit einem Header-Symbol (settings-cog, home…) und einer Funktion. header: { enabled: false } verbirgt den gesamten Header, wenn Ihre Anwendung bereits eine eigene Leiste bereitstellt.
  • history aktiviert das Panel für vergangene Gespräche, mit oder ohne Umbenennung und Löschung. Deaktivieren Sie es, wenn das Konzept eines Threads für Ihren Anwendungsfall keinen Sinn ergibt, beispielsweise bei einem Support-Assistenten ohne Benutzerkonten.
  • threadItemActions.feedback zeigt Daumen-hoch- und Daumen-runter-Buttons unter Antworten an. Jeder Klick gelangt an Ihren Server in der add_feedback-Methode Ihres ChatKitServer (thread_id, item_ids, feedback auf 'positive' oder 'negative' gesetzt). Dies ist das Rohmaterial für Ihre Evaluierungen. retry fügt den Button hinzu, der eine Antwort neu generiert.
  • disclaimer zeigt einen kurzen Markdown-Text unter dem Komponisten an.

Sprache

Standardmäßig verwendet ChatKit die Sprache des Browsers. Wenn Ihre Anwendung eine eigene Spracheinstellung hat, erzwingen Sie diese mit locale: 'en' oder einer regionalen Variante wie 'en-US' oder 'en-GB'. Jede Anfrage, die an Ihren Server gesendet wird, enthält diese Sprache im Accept-Language-Header: Nutzen Sie sie, damit der Assistent antwortet und Ihre Werkzeugnachrichten in derselben Sprache wie die Oberfläche übersetzt werden.

Alles zusammengefasst

Hier ist eine vollständige Konfiguration, die mit @openai/chatkit-react 1.6.1 so kompiliert wurde:

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" />;
}

Wichtige Erkenntnisse

  • Alle Anpassungen erfolgen über ein einziges Options-Objekt, identisch in React (useChatKit) und mit dem Web-Komponenten (setOptions)
  • ChatKit renderisiert in einem Iframe: Ihr CSS gestaltet nur den Container; alles andere geht über theme
  • theme: colorScheme, color.accent, radius, density, typography mit geschlossenen Werten, die von TypeScript validiert werden
  • startScreen (Begrüßung und Vorschläge), composer (Platzhalter, Werkzeuge, Anhänge), header, history, threadItemActions, disclaimer und locale vervollständigen die Oberfläche
  • Anhänge und Benutzerfeedback erfordern Server-seitige Unterstützung: uploadStrategy und AttachmentStore, sowie die add_feedback-Methode