Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Temos ir tinkinimas

Paskaita 18 iš 25 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Vienas parinkčių objektas
  2. Tema
  3. Pradžios ekranas
  4. Kompozitorius
  5. Antraštė, istorija ir atsakymai
  6. Kalba
  7. Viskas kartu
  8. Svarbiausi punktai

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/chatkit 1.9.0; visas pavyzdys patikrintas kompiliuojant TypeScript. Du pavadinimai skiriasi gairėse ir išleistame pakete, o šioje pamokoje laikomasi paketo: label (ne name) pradžios ekrano pasiūlymams ir leftAction bei rightAction (ne customButtonLeft ir customButtonRight) antraštės mygtukams. Šaltiniai: Temos ir tinkinimas ChatKit · ChatKitOptions nuoroda · 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:

ParinktisReikšmėsPoveikis
colorScheme'light', 'dark'Šviesi (numatytoji) arba tamsi tema
color.accentprimary (šešiakampis kodas, rgb(), hsl()…), level nuo 0 iki 3Sąsajos akcento spalva ir paletės intensyvumas
color.grayscalehue laipsniais, tint nuo 0 iki 9, shade nuo −4 iki 4Pilkos paletės atspalvis ir tonas
color.surfacebackground, foregroundPavirš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
typographyfontFamily, 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)" },
  • header rodo fiksuotą pavadinimą (kitaip – dabartinio siūlo pavadinimą) ir iki dviejų tinkintų mygtukų: leftAction ir rightAction. Kiekvienas jų turi antraštės piktogramą (settings-cog, home…) ir funkciją. Nustačius header: { 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.feedback rodo nykščio aukštyn ir žemyn mygtukus po atsakymais. Kiekvienas paspaudimas pasiekia jūsų serverį ChatKitServer metodo add_feedback pagalba (thread_id, item_ids, feedback nustatytas į 'positive' arba 'negative'). Tai žaliava jūsų vertinimams. retry prideda mygtuką, kuris sugeneruoja atsakymą iš naujo.
  • disclaimer rodo 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, typography su uždaromis reikšmėmis, kurias patikrina TypeScript
  • startScreen (pasisveikinimas ir pasiūlymai), composer (vietos rezervavimas, įrankiai, priedai), header, history, threadItemActions, disclaimer ir locale užbaigia sąsają
  • Priedai ir naudotojų atsiliepimai reikalauja serverio pusės palaikymo: uploadStrategy ir AttachmentStore, taip pat metodo add_feedback