Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Teemoittaminen ja mukauttaminen

Oppitunti 18 / 25 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Yksi ainoa asetusten objekti
  2. Teema
  3. Aloitusnäyttö
  4. Syöttökenttä (Composer)
  5. Otsikko, historia ja vastaukset
  6. Kieli
  7. Kaiken yhdistäminen
  8. Keskeiset asiat

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/chatkit 1.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 (ei name) aloitusnäytön ehdotuksille sekä leftAction ja rightAction (ei customButtonLeft ja customButtonRight) 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:

AsetusArvotVaikutus
colorScheme'light', 'dark'Vaalea (oletus) tai tumma teema
color.accentprimary (hex, rgb(), hsl()…), level välillä 0–3Käyttöliittymän korostusväri ja paletin intensiteetti
color.grayscalehue asteina, tint välillä 0–9, shade välillä −4–4Harmaan paletin sävy ja varjostus
color.surfacebackground, foregroundPintavä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
typographyfontFamily, fontFamilyMono, baseSize (14–18), fontSourcesFontit 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)" },
  • header näyttää kiinteän otsikon (muuten nykyisen ketjun otsikon) ja enintään kaksi mukautettua painiketta, leftAction ja rightAction, joista kummassakin on otsikkokuvake (settings-cog, home…) ja funktio. Asetus header: { enabled: false } piilottaa koko otsikon, jos sovelluksesi tarjoaa jo oman palkkinsa.
  • history ottaa 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.feedback näyttää peukalo ylös - ja alas -painikkeet vastausten alla. Jokainen napsautus saapuu palvelimellesi metodissa add_feedback luokassa ChatKitServer (thread_id, item_ids, feedback asetettu arvoon 'positive' tai 'negative'). Tämä on raaka-aine arvioinneillesi. retry lisää painikkeen, joka uudelleentuottaa vastauksen.
  • disclaimer nä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 arvot
  • startScreen (tervehdys ja ehdotukset), composer (paikkateksti, työkalut, liitteet), header, history, threadItemActions, disclaimer ja locale täydentävät käyttöliittymää
  • Liitteet ja käyttäjäpalaute vaativat palvelinpuolen tukea: uploadStrategy ja AttachmentStore sekä metodi add_feedback