Teemad ja kohandamine
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026. Eelmine versioon tugines komponentidele ja valikutele, mida ChatKitis ei eksisteeri:
ChatProvider,MessageInput, kohandatud sõnumite renderdamine ja sisestatud stiililehed. Nüüd järgib see OpenAI Teemad ja kohandamine juhendit ja tüüpe paketist@openai/chatkit1.9.0; täielik näide on kontrollitud TypeScripti kompilaatoriga. Kaks nime erinevad juhendi ja avaldatud paketi vahel ning see õppetund järgib paketti:label(mittename) algusekraani ettepanekute jaoks ningleftActionjarightAction(mittecustomButtonLeftjacustomButtonRight) päisenuppude jaoks. Allikad: Teemad ja kohandamine ChatKitis ·ChatKitOptionsviide · ChatKit Studio.
Üksainus valikute objekt
Kogu ChatKiti kohandamine toimub üheainsa valikute objekti kaudu. Reactis annad selle edasi funktsioonile useChatKit({...}); veebikomponendi puhul meetodile chatkit.setOptions({...}). Kuju on mõlemal juhul identne, nii et siin õpitu kehtib iga integratsiooni kohta.
Üks järeldus tuleneb eelmises tunnis käsitletud arhitektuurist: ChatKit renderdab iframe’i sees, seega ei ulatu sinu stiilileht sinna. Sinu CSS-reeglid kehtivad ainult konteinerile – suurusele ja asukohale, mille annad elemendile <ChatKit className="…" />. Kõik muu konfigureeritakse valikute kaudu. See on hoolduse seisukohalt hea uudis: ChatKiti uuendus ei saa rikkuda CSS-selektoreid, mida ei eksisteeri.
Et proovida valikuid ilma koodi kirjutamata, näitab ChatKit Studio mänguväljak reaalajas renderdamist.
Teema
Teema juhib üldist välimust: värviskeem, rõhuvärv, nurkade raadius, tihedus ja tüpograafia.
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 },
},
});
Igal seadel on kindel väärtuste hulk, mille TypeScript sinu eest valideerib:
| Valik | Väärtused | Mõju |
|---|---|---|
colorScheme | 'light', 'dark' | Hele (vaikimisi) või tume teema |
color.accent | primary (hex, rgb(), hsl()…), level vahemikus 0 kuni 3 | Liidese rõhuvärv ja paleti intensiivsus |
color.grayscale | hue kraadides, tint vahemikus 0 kuni 9, shade vahemikus −4 kuni 4 | Halli paleti toon ja varjund |
color.surface | background, foreground | Pinnavärvid: taust ja esiplaan (tekst, ikoonid) |
radius | 'pill', 'round', 'soft', 'sharp' | Mullide, nuppude ja väljade nurkade raadius |
density | 'compact', 'normal', 'spacious' | Üldine vahemaa |
typography | fontFamily, fontFamilyMono, baseSize (14 kuni 18), fontSources | Fondid ja baassuurus; fontSources laadib veebifondi (family, src, weight…) |
Et järgida kasutaja eelistust, vali skeem valikute koostamisel, näiteks kasutades window.matchMedia('(prefers-color-scheme: dark)').matches. Aktsepteeritakse ka teemat, mis on taandatud stringiks, theme: 'dark', kui soovid määrata ainult värviskeemi.
Algusekraan
Tühi lõim võib tunduda hirmutav. Algusekraan asendab selle tervituse ja ettepanekutega, mis näitavad kasutajale, mida assistent teha saab:
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 on nupu tekst, prompt on sõnum, mis saadetakse kasutaja klõpsamisel, ja icon on nimi ChatKiti ikoonide loendist (search, write, calendar, lightbulb…) või Lucide ikoon kujul 'lucide:name'.
Komposeerija
Objekt composer konfigureerib kohahoidja teksti, kasutajale pakutavad tööriistad ja manused:
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 faili kohta
accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
},
},
Menüüst valitud tööriist saadetakse serverisse järgmise vooru tööriista eelistusena; pead seda oma agendis arvesse võtma.
Manused on vaikimisi keelatud ja nende lubamine nõuab serveripoolset tööd. Oma serveriga pead ka määrama api sees, kuidas faile üles laaditakse: uploadStrategy: { type: 'direct', uploadUrl: '…' } (liides postitab faili sinu lõpppunkti) või { type: 'two_phase' } (see pärib allkirjastatud URL-i ja laadib seejärel faili sinu salvestusruumi). Pythoni poolel pakud siis AttachmentStore. Ära märgi enabled: true, enne kui see torustik on olemas.
Päis, ajalugu ja vastused
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)" },
headerkuvab fikseeritud pealkirja (vastasel juhul praeguse lõime pealkirja) ja kuni kaks kohandatud nuppu,leftActionjarightAction, millest kummalgi on päise ikoon (settings-cog,home…) ja funktsioon.header: { enabled: false }peidab kogu päise, kui sinu rakendus pakub juba oma riba.historylubab varasemate vestluste paneeli, koos ümbernimetamise ja kustutamisega või ilma. Keela see, kui lõime mõiste ei ole sinu kasutusjuhu jaoks mõttekas, näiteks tugiteenuse assistendi puhul ilma kasutajakontodeta.threadItemActions.feedbackkuvab vastuste all üles- ja allanäpu nupud. Iga klõps jõuab sinu serverisse meetodisadd_feedbacksinuChatKitServeris (thread_id,item_ids,feedbackväärtusega'positive'või'negative'). See on toormaterjal sinu hindamiste jaoks.retrylisab nupu, mis genereerib vastuse uuesti.disclaimerkuvab komposeerija all lühikese Markdown-teksti.
Keel
Vaikimisi kasutab ChatKit brauseri keelt. Kui sinu rakendusel on oma keeleseade, sunni seda kasutama locale: 'en' või regionaalse variandiga nagu 'en-US' või 'en-GB'. Iga sinu serverisse saadetud päring kannab seda keelt päises Accept-Language: kasuta seda, et panna agent vastama ja tõlkima oma tööriistateateid samas keeles kui liides.
Kõige kokkuvõtmine
Siin on täielik konfiguratsioon, kompileeritud sellisena paketiga @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" />;
}
Peamised punktid
- Kogu kohandamine toimub üheainsa valikute objekti kaudu, mis on identne nii Reactis (
useChatKit) kui ka veebikomponendiga (setOptions) - ChatKit renderdab iframe’is: sinu CSS vormindab ainult konteinerit; kõik muu läheb
themekaudu theme:colorScheme,color.accent,radius,density,typography, koos TypeScripti poolt valideeritud kindlate väärtustegastartScreen(tervitus ja ettepanekud),composer(kohahoidja, tööriistad, manused),header,history,threadItemActions,disclaimerjalocaletäiendavad liidest- Manused ja kasutaja tagasiside nõuavad serveripoolset tuge:
uploadStrategyjaAttachmentStore, pluss meetodadd_feedback