Tēmu pielāgošana un konfigurēšana
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī. Iepriekšējā versija balstījās uz komponentēm un opcijām, kas ChatKit neeksistē:
ChatProvider,MessageInput, pielāgota ziņojumu attēlošana un injicēti stila faili. Tagad tā seko OpenAI Tēmu pielāgošanas un konfigurēšanas rokasgrāmatai un tipiem no@openai/chatkit1.9.0; pilnais piemērs ir pārbaudīts, kompilējot TypeScript. Divi nosaukumi atšķiras starp rokasgrāmatu un publicēto pakotni, un šī nodarbība seko pakotnei:label(nevisname) sākuma ekrāna ieteikumiem, kā arīleftActionunrightAction(neviscustomButtonLeftuncustomButtonRight) galvenes pogām. Avoti: Tēmu pielāgošana un konfigurēšana ChatKit ·ChatKitOptionsatsauce · ChatKit Studio.
Vienots opciju objekts
Visa ChatKit pielāgošana notiek, izmantojot vienu opciju objektu. React vidē tu to nodod funkcijai useChatKit({...}); izmantojot tīmekļa komponenti – chatkit.setOptions({...}). Abos gadījumos struktūra ir identiska, tāpēc viss, ko tu šeit apgūsti, attiecas uz katru integrāciju.
No iepriekšējā nodarbībā aplūkotās arhitektūras izriet vienas sekas: ChatKit tiek attēlots iframe ietvarā, tāpēc tavs stila fails tam nevar piekļūt. Tavi CSS noteikumi attiecas tikai uz konteineru – izmēru un pozīciju, ko tu piešķir elementam <ChatKit className="…" />. Viss pārējais tiek konfigurēts, izmantojot opcijas. Tas ir labs jaunums apkopei: ChatKit atjauninājums nevar sabojāt CSS selektorus, kas neeksistē.
Lai izmēģinātu opcijas, nerakstot kodu, ChatKit Studio spēļu laukums parāda attēlojumu reāllaikā.
Tēma
Tēma kontrolē kopējo izskatu: krāsu shēmu, akcenta krāsu, stūru rādiusu, blīvumu un tipogrāfiju.
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 },
},
});
Katrai iestatījumam ir slēgta vērtību kopa, ko TypeScript tavā vietā validē:
| Opcija | Vērtības | Ietekme |
|---|---|---|
colorScheme | 'light', 'dark' | Gaiša (noklusējuma) vai tumša tēma |
color.accent | primary (hex, rgb(), hsl()…), level no 0 līdz 3 | Saskarnes akcenta krāsa un paletes intensitāte |
color.grayscale | hue grādos, tint no 0 līdz 9, shade no −4 līdz 4 | Pelēkās paletes tonis un ēnojums |
color.surface | background, foreground | Virsmu krāsas: fons un priekšplāns (teksts, ikonas) |
radius | 'pill', 'round', 'soft', 'sharp' | Stūru rādiuss burbuļiem, pogām un laukiem |
density | 'compact', 'normal', 'spacious' | Kopējā atstarpe |
typography | fontFamily, fontFamilyMono, baseSize (14 līdz 18), fontSources | Fonti un bāzes izmērs; fontSources ielādē tīmekļa fontu (family, src, weight…) |
Lai sekotu lietotāja preferencēm, izvēlies shēmu opciju veidošanas brīdī, piemēram, izmantojot window.matchMedia('(prefers-color-scheme: dark)').matches. Tiek pieņemts arī theme, kas reducēts uz virkni, theme: 'dark', ja tev jāiestata tikai krāsu shēma.
Sākuma ekrāns
Tukšs pavediens var šķist biedējošs. Sākuma ekrāns to aizstāj ar sveicienu un ieteikumiem, kas lietotājam parāda, ko asistents spēj darīt:
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 ir pogas teksts, prompt ir ziņojums, kas tiek nosūtīts, kad lietotājs noklikšķina, un icon ir nosaukums no ChatKit ikonu saraksta (search, write, calendar, lightbulb…) vai Lucide ikona formātā 'lucide:name'.
Komponents ziņojumu rakstīšanai
Objekts composer konfigurē viettura tekstu, lietotājam piedāvātos rīkus un pielikumus:
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 par failu
accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
},
},
Rīks, kas izvēlēts no izvēlnes, tiek nosūtīts serverim kā rīka preference nākamajam gājienam; tev tas jāņem vērā savā aģentā.
Pielikumi pēc noklusējuma ir atspējoti, un to iespējošana prasa darbu servera pusē. Izmantojot savu serveri, tev api jānorāda arī tas, kā tiek augšupielādēti faili: uploadStrategy: { type: 'direct', uploadUrl: '…' } (saskarne publicē failu tavā galapunktā) vai { type: 'two_phase' } (tā pieprasa parakstītu URL, pēc tam augšupielādē failu tavā krātuvē). Python pusē tad tu nodrošini AttachmentStore. Neatzīmē enabled: true, kamēr šī cauruļvada nav izveidota.
Galvene, vēsture un atbildes
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)" },
headerattēlo fiksētu virsrakstu (pretējā gadījumā – pašreizējā pavediena virsrakstu) un līdz divām pielāgotām pogām:leftActionunrightAction, katrai ar galvenes ikonu (settings-cog,home…) un funkciju.header: { enabled: false }paslēpj visu galveni, ja tava lietotne jau nodrošina savu joslu.historyiespējo pagātnes sarunu paneli, ar vai bez pārdēvēšanas un dzēšanas funkcijām. Atspējo to, ja pavediena jēdziens tavam lietojumam nav jēdzīgs, piemēram, atbalsta asistentam bez lietotāju kontiem.threadItemActions.feedbackattēlo patīk/nepatīk pogas zem atbildēm. Katrs klikšķis nonāk tavā serverī, izmantojotChatKitServermetodiadd_feedback(thread_id,item_ids,feedbackiestatīts uz'positive'vai'negative'). Tas ir izejmateriāls taviem novērtējumiem.retrypievieno pogu, kas ģenerē atbildi no jauna.disclaimerattēlo īsu Markdown tekstu zem ziņojumu rakstīšanas komponentes.
Valoda
Pēc noklusējuma ChatKit izmanto pārlūkprogrammas valodu. Ja tavai lietotnei ir sava valodas iestatījuma, piespied to ar locale: 'en' vai reģionālu variantu, piemēram, 'en-US' vai 'en-GB'. Katrs pieprasījums, kas nosūtīts tavam serverim, šo valodu nes Accept-Language galvenē: izmanto to, lai asistents atbildētu un lai tulkotu savu rīku ziņojumus tajā pašā valodā, kurā ir saskarne.
Viss kopā
Lūk, pilnīga konfigurācija, kas tiek kompilēta tieši tāda, kāda ir, izmantojot @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" />;
}
Galvenās atziņas
- Visa pielāgošana notiek, izmantojot vienu opciju objektu, kas ir identisks gan React (
useChatKit), gan ar tīmekļa komponenti (setOptions) - ChatKit tiek attēlots iframe: tavs CSS stilizē tikai konteineru; viss pārējais notiek caur
theme theme:colorScheme,color.accent,radius,density,typographyar slēgtām vērtībām, ko validē TypeScriptstartScreen(sveiciens un ieteikumi),composer(vietturis, rīki, pielikumi),header,history,threadItemActions,disclaimerunlocalepapildina saskarni- Pielikumi un lietotāju atsauksmes prasa atbalstu servera pusē:
uploadStrategyunAttachmentStore, kā arī metodiadd_feedback