Motywy i dostosowywanie
Na tej stronie
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/chatkitw 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 niename) dla sugestii na ekranie startowym orazleftActionirightAction(a niecustomButtonLefticustomButtonRight) dla przycisków w nagłówku. Źródła: Theming and customization in ChatKit ·ChatKitOptionsreference · 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:
| Opcja | Wartości | Efekt |
|---|---|---|
colorScheme | 'light', 'dark' | Jasny (domyślny) lub ciemny motyw |
color.accent | primary (hex, rgb(), hsl()…), level od 0 do 3 | Kolor akcentujący interfejsu i intensywność palety |
color.grayscale | hue w stopniach, tint od 0 do 9, shade od −4 do 4 | Odcień i nasycenie palety szarości |
color.surface | background, foreground | Kolory 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 |
typography | fontFamily, fontFamilyMono, baseSize (14 do 18), fontSources | Czcionki 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)" },
headerwyświetla stały tytuł (w przeciwnym razie tytuł bieżącego wątku) oraz do dwóch niestandardowych przycisków:leftActionirightAction, 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.historywłą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.feedbackwyświetla przyciski kciuka w górę i w dół pod odpowiedziami. Każde kliknięcie trafia na Twój serwer w metodzieadd_feedbackTwojegoChatKitServer(thread_id,item_ids,feedbackustawione na'positive'lub'negative'). To surowy materiał do Twoich ewaluacji.retrydodaje przycisk regenerujący odpowiedź.disclaimerwyś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 TypeScriptstartScreen(powitanie i sugestie),composer(placeholder, narzędzia, załączniki),header,history,threadItemActions,disclaimerorazlocaleuzupełniają interfejs- Załączniki i opinie użytkowników wymagają wsparcia po stronie serwera:
uploadStrategyiAttachmentStore, plus metodaadd_feedback