Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Teemad ja kohandamine

Õppetund 18 / 25 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Üksainus valikute objekt
  2. Teema
  3. Algusekraan
  4. Komposeerija
  5. Päis, ajalugu ja vastused
  6. Keel
  7. Kõige kokkuvõtmine
  8. Peamised punktid

Õ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/chatkit 1.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 (mitte name) algusekraani ettepanekute jaoks ning leftAction ja rightAction (mitte customButtonLeft ja customButtonRight) päisenuppude jaoks. Allikad: Teemad ja kohandamine ChatKitis · ChatKitOptions viide · 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:

ValikVäärtusedMõju
colorScheme'light', 'dark'Hele (vaikimisi) või tume teema
color.accentprimary (hex, rgb(), hsl()…), level vahemikus 0 kuni 3Liidese rõhuvärv ja paleti intensiivsus
color.grayscalehue kraadides, tint vahemikus 0 kuni 9, shade vahemikus −4 kuni 4Halli paleti toon ja varjund
color.surfacebackground, foregroundPinnavärvid: taust ja esiplaan (tekst, ikoonid)
radius'pill', 'round', 'soft', 'sharp'Mullide, nuppude ja väljade nurkade raadius
density'compact', 'normal', 'spacious'Üldine vahemaa
typographyfontFamily, fontFamilyMono, baseSize (14 kuni 18), fontSourcesFondid 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)" },
  • header kuvab fikseeritud pealkirja (vastasel juhul praeguse lõime pealkirja) ja kuni kaks kohandatud nuppu, leftAction ja rightAction, 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.
  • history lubab 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.feedback kuvab vastuste all üles- ja allanäpu nupud. Iga klõps jõuab sinu serverisse meetodis add_feedback sinu ChatKitServeris (thread_id, item_ids, feedback väärtusega 'positive' või 'negative'). See on toormaterjal sinu hindamiste jaoks. retry lisab nupu, mis genereerib vastuse uuesti.
  • disclaimer kuvab 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 theme kaudu
  • theme: colorScheme, color.accent, radius, density, typography, koos TypeScripti poolt valideeritud kindlate väärtustega
  • startScreen (tervitus ja ettepanekud), composer (kohahoidja, tööriistad, manused), header, history, threadItemActions, disclaimer ja locale täiendavad liidest
  • Manused ja kasutaja tagasiside nõuavad serveripoolset tuge: uploadStrategy ja AttachmentStore, pluss meetod add_feedback