Temos ir tinkinimas
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. Ankstesnė versija rėmėsi komponentais ir parinktimis, kurių ChatKit nėra:
ChatProvider,MessageInput, pranešimų atvaizdavimas pagal užsakymą ir įterpti stiliaus lapai. Dabar ji laikosi OpenAI Temos ir tinkinimo gairių bei tipų iš@openai/chatkit1.9.0; visas pavyzdys patikrintas kompiliuojant TypeScript. Du pavadinimai skiriasi gairėse ir išleistame pakete, o šioje pamokoje laikomasi paketo:label(nename) pradžios ekrano pasiūlymams irleftActionbeirightAction(necustomButtonLeftircustomButtonRight) antraštės mygtukams. Šaltiniai: Temos ir tinkinimas ChatKit ·ChatKitOptionsnuoroda · ChatKit Studio.
Vienas parinkčių objektas
Visas ChatKit tinkinimas atliekamas per vieną parinkčių objektą. „React“ aplinkoje jį perduodate funkcijai useChatKit({...}); naudodami žiniatinklio komponentą – chatkit.setOptions({...}). Abiem atvejais struktūra identiška, todėl čia išmokti dalykai tinka bet kokiai integracijai.
Iš ankstesnėje pamokoje nagrinėtos architektūros išplaukia viena pasekmė: ChatKit atvaizduojamas „iframe“ rėmelyje, todėl jūsų stiliaus lapas iki jo nepasiekia. Jūsų CSS taisyklės taikomos tik konteineriui – dydžiui ir pozicijai, kuriuos nustatote elementui <ChatKit className="…" />. Visa kita konfigūruojama per parinktis. Tai gera žinia palaikymui: ChatKit atnaujinimas negali sugadinti CSS selektorių, kurių nėra.
Norėdami išbandyti parinktis nerašydami kodo, naudokite ChatKit Studio žaidimų aikštelę, kurioje matomas gyvas atvaizdavimas.
Tema
Tema valdo bendrą išvaizdą: spalvų schemą, akcento spalvą, kampų spindulį, tankumą ir tipografiją.
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 },
},
});
Kiekvienas nustatymas turi uždarą reikšmių rinkinį, kurį jūsų vardu patikrina TypeScript:
| Parinktis | Reikšmės | Poveikis |
|---|---|---|
colorScheme | 'light', 'dark' | Šviesi (numatytoji) arba tamsi tema |
color.accent | primary (šešiakampis kodas, rgb(), hsl()…), level nuo 0 iki 3 | Sąsajos akcento spalva ir paletės intensyvumas |
color.grayscale | hue laipsniais, tint nuo 0 iki 9, shade nuo −4 iki 4 | Pilkos paletės atspalvis ir tonas |
color.surface | background, foreground | Paviršiaus spalvos: fonas ir priekinis planas (tekstas, piktogramos) |
radius | 'pill', 'round', 'soft', 'sharp' | Burbulų, mygtukų ir laukų kampų spindulys |
density | 'compact', 'normal', 'spacious' | Bendras tarpų dydis |
typography | fontFamily, fontFamilyMono, baseSize (nuo 14 iki 18), fontSources | Šriftai ir bazinis dydis; fontSources įkelia žiniatinklio šriftą (family, src, weight…) |
Norėdami atsižvelgti į naudotojo pageidavimus, schemą pasirinkite kurdami parinktis, pavyzdžiui, naudodami window.matchMedia('(prefers-color-scheme: dark)').matches. Jei reikia nustatyti tik spalvų schemą, priimama ir tema, sutrumpinta iki eilutės: theme: 'dark'.
Pradžios ekranas
Tuščias siūlas gali atrodyti bauginančiai. Pradžios ekranas jį pakeičia pasisveikinimu ir pasiūlymais, kurie parodo naudotojui, ką asistentas gali nuveikti:
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 yra mygtuko tekstas, prompt – žinutė, išsiunčiama naudotojui paspaudus, o icon – pavadinimas iš ChatKit piktogramų sąrašo (search, write, calendar, lightbulb…) arba „Lucide“ piktograma formatu 'lucide:name'.
Kompozitorius
Objektas composer konfigūruoja vietos rezervavimo tekstą, naudotojui siūlomus įrankius ir priedus:
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'] },
},
},
Iš meniu pasirinktas įrankis siunčiamas serveriui kaip įrankio nuostata kitam ėjimui; į tai turite atsižvelgti savo agente.
Priedai pagal nutylėjimą išjungti, o juos įjungus reikia atlikti darbus serverio pusėje. Naudodami savo serverį, taip pat turite nurodyti api, kaip įkeliami failai: uploadStrategy: { type: 'direct', uploadUrl: '…' } (sąsaja išsiunčia failą į jūsų galinį tašką) arba { type: 'two_phase' } (ji prašo pasirašyto URL, tada įkelia failą į jūsų saugyklą). Python pusėje tuomet pateikiate AttachmentStore. Nežymėkite enabled: true, kol ši grandinė nėra sukurta.
Antraštė, istorija ir atsakymai
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)" },
headerrodo fiksuotą pavadinimą (kitaip – dabartinio siūlo pavadinimą) ir iki dviejų tinkintų mygtukų:leftActionirrightAction. Kiekvienas jų turi antraštės piktogramą (settings-cog,home…) ir funkciją. Nustačiusheader: { enabled: false }, visa antraštė paslepiama, kai jūsų programa jau turi savo juostą.historyįjungia ankstesnių pokalbių skydelį su galimybe pervadinti ir ištrinti arba be jų. Išjunkite tai, jei siūlo sąvoka jūsų atveju neturi prasmės, pavyzdžiui, palaikymo asistentui be naudotojų paskyrų.threadItemActions.feedbackrodo nykščio aukštyn ir žemyn mygtukus po atsakymais. Kiekvienas paspaudimas pasiekia jūsų serverįChatKitServermetodoadd_feedbackpagalba (thread_id,item_ids,feedbacknustatytas į'positive'arba'negative'). Tai žaliava jūsų vertinimams.retryprideda mygtuką, kuris sugeneruoja atsakymą iš naujo.disclaimerrodo trumpą „Markdown“ tekstą po kompozitoriumi.
Kalba
Pagal nutylėjimą ChatKit naudoja naršyklės kalbą. Jei jūsų programa turi savo kalbos nustatymą, priverskite ją naudoti parametru locale: 'en' arba regioniniu variantu, pvz., 'en-US' arba 'en-GB'. Kiekvienas jūsų serveriui siunčiamas užklausos šią kalbą perduoda Accept-Language antraštėje: naudokite ją, kad agentas atsakytų ir kad išverstumėte savo įrankių žinutes ta pačia kalba kaip ir sąsaja.
Viskas kartu
Štai pilna konfigūracija, tokia pati kompiliuojama su @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" />;
}
Svarbiausi punktai
- Visas tinkinimas atliekamas per vieną parinkčių objektą, identišką „React“ (
useChatKit) ir naudojant žiniatinklio komponentą (setOptions) - ChatKit atvaizduojamas „iframe“ rėmelyje: jūsų CSS stilizuoja tik konteinerį; visa kita eina per
theme theme:colorScheme,color.accent,radius,density,typographysu uždaromis reikšmėmis, kurias patikrina TypeScriptstartScreen(pasisveikinimas ir pasiūlymai),composer(vietos rezervavimas, įrankiai, priedai),header,history,threadItemActions,disclaimerirlocaleužbaigia sąsają- Priedai ir naudotojų atsiliepimai reikalauja serverio pusės palaikymo:
uploadStrategyirAttachmentStore, taip pat metodoadd_feedback