Przejdź do głównej treści
Polski— Wybierz język
Menu

Motywy i dostosowywanie

Lekcja 18 z 25 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Pojedynczy obiekt opcji
  2. Motyw
  3. Ekran startowy
  4. Kompozytor
  5. Nagłówek, historia i odpowiedzi
  6. Język
  7. Łącząc wszystko w całość
  8. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opierała się na komponentach i opcjach, które nie istnieją w ChatKit: ChatProvider, MessageInput, niestandardowe renderowanie wiadomości oraz injectowane arkusze stylów. Obecnie podąża za przewodnikiem OpenAI Theming and customization oraz typami z pakietu @openai/chatkit w wersji 1.9.0; kompletny przykład został zweryfikowany poprzez kompilację TypeScript. Dwie nazwy różnią się między przewodnikiem a opublikowanym pakietem i ta lekcja stosuje się do pakietu: label (a nie name) dla sugestii na ekranie startowym oraz leftAction i rightAction (a nie customButtonLeft i customButtonRight) dla przycisków w nagłówku. Źródła: Theming and customization in ChatKit · ChatKitOptions reference · ChatKit Studio.

Pojedynczy obiekt opcji

Całe dostosowywanie ChatKit odbywa się za pomocą jednego obiektu opcji. W React przekazujesz go do useChatKit({...}); w przypadku komponentu webowego — do chatkit.setOptions({...}). Struktura jest identyczna w obu przypadkach, więc wiedza zdobyta tutaj dotyczy każdej integracji.

Jedną z konsekwencji architektury omówionej w poprzedniej lekcji jest fakt, że ChatKit renderuje się wewnątrz iframe, więc Twój arkusz stylów nie może do niego dotrzeć. Twoje reguły CSS dotyczą tylko kontenera — rozmiaru i pozycji, które nadajesz elementowi <ChatKit className="…" />. Wszystko inne konfigurujesz poprzez opcje. To dobra wiadomość dla utrzymania kodu: aktualizacja ChatKit nie może zepsuć selektorów CSS, które nie istnieją.

Aby wypróbować opcje bez pisania kodu, plac zabaw ChatKit Studio pokazuje renderowanie na żywo.

Motyw

Motyw kontroluje ogólny wygląd: schemat kolorów, kolor akcentujący, zaokrąglenie rogów, gęstość i 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 },
  },
});

Każde ustawienie ma zamknięty zestaw wartości, które TypeScript waliduje za Ciebie:

OpcjaWartościEfekt
colorScheme'light', 'dark'Jasny (domyślny) lub ciemny motyw
color.accentprimary (hex, rgb(), hsl()…), level od 0 do 3Kolor akcentujący interfejsu i intensywność palety
color.grayscalehue w stopniach, tint od 0 do 9, shade od −4 do 4Odcień i nasycenie palety szarości
color.surfacebackground, foregroundKolory powierzchni: tło i pierwszy plan (tekst, ikony)
radius'pill', 'round', 'soft', 'sharp'Zaokrąglenie rogów dla dymków, przycisków i pól
density'compact', 'normal', 'spacious'Ogólne odstępy
typographyfontFamily, fontFamilyMono, baseSize (14 do 18), fontSourcesCzcionki i bazowy rozmiar; fontSources ładuje czcionkę sieciową (family, src, weight…)

Aby dostosować się do preferencji użytkownika, wybierz schemat podczas budowania opcji, na przykład używając window.matchMedia('(prefers-color-scheme: dark)').matches. Akceptowane jest również przekazanie theme jako ciągu znaków, np. theme: 'dark', gdy chcesz ustawić tylko schemat kolorów.

Ekran startowy

Pusty wątek może być onieśmielający. Ekran startowy zastępuje go powitaniem i sugestiami, które pokazują użytkownikowi, co asystent potrafi zrobić:

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 to tekst przycisku, prompt to wiadomość wysyłana po kliknięciu przez użytkownika, a icon to nazwa z listy ikon ChatKit (search, write, calendar, lightbulb…) lub ikona Lucide w formie 'lucide:name'.

Kompozytor

Obiekt composer konfiguruje tekst zastępczy, narzędzia oferowane użytkownikowi oraz załączniki:

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'] },
  },
},

Narzędzie wybrane z menu jest wysyłane do serwera jako preferencja narzędzia dla następnej tury; musisz uwzględnić to w swoim agencie.

Załączniki są domyślnie wyłączone, a ich włączenie wymaga pracy po stronie serwera. Przy użyciu własnego serwera musisz również określić w api, jak przesyłane są pliki: uploadStrategy: { type: 'direct', uploadUrl: '…' } (interfejs wysyła plik do Twojego punktu końcowego) lub { type: 'two_phase' } (żąda podpisanego URL, a następnie przesyła plik do Twojego magazynu). Po stronie Pythona dostarczasz wtedy AttachmentStore. Nie zaznaczaj enabled: true, dopóki ten potok nie będzie istniał.

Nagłówek, historia i odpowiedzi

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 wyświetla stały tytuł (w przeciwnym razie tytuł bieżącego wątku) oraz do dwóch niestandardowych przycisków: leftAction i rightAction, każdy z ikoną w nagłówku (settings-cog, home…) i funkcją. header: { enabled: false } ukrywa cały nagłówek, gdy Twoja aplikacja zapewnia już własny pasek.
  • history włącza panel przeszłych rozmów, z możliwością zmiany nazwy i usuwania lub bez. Wyłącz go, gdy koncepcja wątku nie ma sensu w Twoim przypadku użycia, na przykład dla asystenta wsparcia bez kont użytkowników.
  • threadItemActions.feedback wyświetla przyciski kciuka w górę i w dół pod odpowiedziami. Każde kliknięcie trafia na Twój serwer w metodzie add_feedback Twojego ChatKitServer (thread_id, item_ids, feedback ustawione na 'positive' lub 'negative'). To surowy materiał do Twoich ewaluacji. retry dodaje przycisk regenerujący odpowiedź.
  • disclaimer wyświetla krótki tekst w formacie Markdown pod kompozytorem.

Język

Domyślnie ChatKit używa języka przeglądarki. Jeśli Twoja aplikacja ma własne ustawienie języka, wymuś je za pomocą locale: 'en' lub wariantu regionalnego, takiego jak 'en-US' lub 'en-GB'. Każde żądanie wysłane do Twojego serwera niesie ten język w nagłówku Accept-Language: użyj go, aby agent odpowiadał i tłumaczył wiadomości narzędzi w tym samym języku co interfejs.

Łącząc wszystko w całość

Oto kompletna konfiguracja, skompilowana tak jak jest z @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" />;
}

Kluczowe wnioski

  • Całe dostosowywanie odbywa się przez pojedynczy obiekt opcji, identyczny w React (useChatKit) i w komponencie webowym (setOptions)
  • ChatKit renderuje się w iframe: Twój CSS styluje tylko kontener; wszystko inne przechodzi przez theme
  • theme: colorScheme, color.accent, radius, density, typography, z zamkniętymi wartościami walidowanymi przez TypeScript
  • startScreen (powitanie i sugestie), composer (placeholder, narzędzia, załączniki), header, history, threadItemActions, disclaimer oraz locale uzupełniają interfejs
  • Załączniki i opinie użytkowników wymagają wsparcia po stronie serwera: uploadStrategy i AttachmentStore, plus metoda add_feedback