Teemoittaminen ja mukauttaminen
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026. Edellinen versio perustui komponentteihin ja vaihtoehtoihin, joita ei ole olemassa ChatKitissä:
ChatProvider,MessageInput, mukautettu viestien renderöinti ja injektoidut tyylitiedostot. Se noudattaa nyt OpenAI:n Teemoittaminen ja mukauttaminen -opasta ja tyyppejä paketista@openai/chatkit1.9.0; koko esimerkki on varmistettu TypeScript-käännöksellä. Kaksi nimeä eroaa oppaan ja julkaistun paketin välillä, ja tämä oppitunti noudattaa pakettia:label(einame) aloitusnäytön ehdotuksille sekäleftActionjarightAction(eicustomButtonLeftjacustomButtonRight) otsikkopainikkeille. Lähteet: Teemoittaminen ja mukauttaminen ChatKitissä ·ChatKitOptions-viite · ChatKit Studio.
Yksi ainoa asetusten objekti
Kaikki ChatKitin mukauttaminen tapahtuu yhden asetusten objektin kautta. Reactissa välität sen funktiolle useChatKit({...}); web-komponentilla puolestaan metodille chatkit.setOptions({...}). Rakenne on molemmissa tapauksissa identtinen, joten tässä oppimasi pätee kaikkiin integraatioihin.
Edellisessä oppitunnissa käsitellystä arkkitehtuurista seuraa yksi seuraamus: ChatKit renderöityy iframe-kehykseen, joten tyylitiedostosi eivät yllä siihen. CSS-sääntösi vaikuttavat vain säiliöön – kokoon ja sijaintiin, jonka määrität elementille <ChatKit className="…" />. Kaikki muu konfiguroidaan asetusten kautta. Tämä on hyvä uutinen ylläpidon kannalta: ChatKitin päivitys ei voi rikkoa CSS-valitsimia, joita ei ole olemassa.
Jos haluat kokeilla asetuksia kirjoittamatta koodia, ChatKit Studio -leikkikenttä näyttää renderöinnin reaaliajassa.
Teema
Teema ohjaa yleistä ulkoasua: väriteemaa, korostusväriä, kulmien säädettä, tiheyttä ja typografiaa.
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 },
},
});
Jokaisella asetuksella on suljettu joukko arvoja, jotka TypeScript validoi puolestasi:
| Asetus | Arvot | Vaikutus |
|---|---|---|
colorScheme | 'light', 'dark' | Vaalea (oletus) tai tumma teema |
color.accent | primary (hex, rgb(), hsl()…), level välillä 0–3 | Käyttöliittymän korostusväri ja paletin intensiteetti |
color.grayscale | hue asteina, tint välillä 0–9, shade välillä −4–4 | Harmaan paletin sävy ja varjostus |
color.surface | background, foreground | Pintavärit: tausta ja foreground (teksti, kuvakkeet) |
radius | 'pill', 'round', 'soft', 'sharp' | Kulmien säde kuplille, painikkeille ja kentille |
density | 'compact', 'normal', 'spacious' | Yleinen välistys |
typography | fontFamily, fontFamilyMono, baseSize (14–18), fontSources | Fontit ja peruskoko; fontSources lataa verkkofontin (family, src, weight…) |
Seurataksesi käyttäjän mieltymyksiä, valitse teema asetuksia rakentaessasi, esimerkiksi käyttämällä window.matchMedia('(prefers-color-scheme: dark)').matches. Myös pelkäksi merkkijonoksi pelkistetty theme, eli theme: 'dark', hyväksytään, jos tarvitset vain väriteeman asettamista.
Aloitusnäyttö
Tyhjä keskusteluketju voi tuntua pelottavalta. Aloitusnäyttö korvaa sen tervehdyksellä ja ehdotuksilla, jotka näyttävät käyttäjälle, mitä avustaja pystyy tekemään:
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 painikkeen teksti, prompt on viesti, joka lähetetään käyttäjän napsautaessa, ja icon on nimi ChatKitin kuvakeluettelosta (search, write, calendar, lightbulb…) tai Lucide-kuvake muodossa 'lucide:name'.
Syöttökenttä (Composer)
Objekti composer määrittää paikkatekstin, käyttäjälle tarjotut työkalut ja liitteet:
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'] },
},
},
Valikosta valittu työkalu lähetetään palvelimelle työkalusuosimuksena seuraavaa vuoroa varten; sinun on otettava tämä huomioon agentissasi.
Liitteet ovat oletuksena pois käytöstä, ja niiden käyttöönotto vaatii palvelinpuolen työtä. Omalla palvelimellasi sinun on myös määritettävä kohdassa api, miten tiedostot ladataan: uploadStrategy: { type: 'direct', uploadUrl: '…' } (rajapinta lähettää tiedoston päätepisteeseesi) tai { type: 'two_phase' } (se pyytää allekirjoitetun URL-osoitteen ja lataa sitten tiedoston tallennustilaasi). Python-puolella tarjoat sitten AttachmentStore:n. Älä laita arvoa enabled: true ennen kuin tämä putki on olemassa.
Otsikko, historia ja vastaukset
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)" },
headernäyttää kiinteän otsikon (muuten nykyisen ketjun otsikon) ja enintään kaksi mukautettua painiketta,leftActionjarightAction, joista kummassakin on otsikkokuvake (settings-cog,home…) ja funktio. Asetusheader: { enabled: false }piilottaa koko otsikon, jos sovelluksesi tarjoaa jo oman palkkinsa.historyottaa käyttöön paneelin aiemmille keskusteluille, joko uudelleennimeämisellä ja poistolla tai ilman. Poista se käytöstä, jos ketjun käsite ei ole järkevä käyttötapauksessasi, esimerkiksi tukiasistentilla, jossa ei ole käyttäjätilejä.threadItemActions.feedbacknäyttää peukalo ylös - ja alas -painikkeet vastausten alla. Jokainen napsautus saapuu palvelimellesi metodissaadd_feedbackluokassaChatKitServer(thread_id,item_ids,feedbackasetettu arvoon'positive'tai'negative'). Tämä on raaka-aine arvioinneillesi.retrylisää painikkeen, joka uudelleentuottaa vastauksen.disclaimernäyttää lyhyen Markdown-tekstin syöttökentän alapuolella.
Kieli
Oletuksena ChatKit käyttää selaimen kieltä. Jos sovelluksellasi on oma kieliasetuksensa, pakota se käyttämään locale: 'en' tai alueellista muunnelmaa kuten 'en-US' tai 'en-GB'. Jokainen palvelimellesi lähetetty pyyntö sisältää tämän kielen otsikossa Accept-Language: käytä sitä saadaksesi agentin vastaamaan ja kääntääksesi työkaluviestisi samalla kielellä kuin käyttöliittymä.
Kaiken yhdistäminen
Tässä on täydellinen konfiguraatio, joka kääntyy sellaisenaan paketilla @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" />;
}
Keskeiset asiat
- Kaikki mukauttaminen tapahtuu yhden asetusten objektin kautta, joka on identtinen Reactissa (
useChatKit) ja web-komponentilla (setOptions) - ChatKit renderöityy iframe-kehykseen: CSS-tyylisi muotoilevat vain säiliön; kaikki muu kulkee
theme:n kautta theme:colorScheme,color.accent,radius,density,typography, joilla on TypeScriptin validoimat suljetut arvotstartScreen(tervehdys ja ehdotukset),composer(paikkateksti, työkalut, liitteet),header,history,threadItemActions,disclaimerjalocaletäydentävät käyttöliittymää- Liitteet ja käyttäjäpalaute vaativat palvelinpuolen tukea:
uploadStrategyjaAttachmentStoresekä metodiadd_feedback