Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Prilagajanje videza in nastavitev

Lekcija 18 od 25 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Enoten objekt z možnostmi
  2. Tema
  3. Začetni zaslon
  4. Sestavljalec sporočil
  5. Glava, zgodovina in odgovori
  6. Jezik
  7. Vse skupaj
  8. Ključne ugotovitve

Lekcija ponovno napisana 3. novembra 2026. Prejšnja različica se je zanašala na komponente in možnosti, ki v ChatKitu ne obstajajo: ChatProvider, MessageInput, prilagojeno izrisovanje sporočil in vbrizgane slogovne predloge. Sedaj sledi vodniku OpenAI Theming and customization in tipom iz paketa @openai/chatkit 1.9.0; celoten primer je bil preverjen s kompilacijo TypeScript. Dve imeni se razlikujeta med vodnikom in objavljenim paketom, ta lekcija pa sledi paketu: label (ne name) za predloge na začetnem zaslonu ter leftAction in rightAction (ne customButtonLeft in customButtonRight) za gumbe v glavi. Viri: Prilagajanje videza v ChatKitu · Referenca ChatKitOptions · ChatKit Studio.

Enoten objekt z možnostmi

Vse prilagoditve ChatKita potekajo prek enotnega objekta z možnostmi. V Reactu ga posredujete funkciji useChatKit({...}); pri spletnem elementu pa metodi chatkit.setOptions({...}). Oblika je v obeh primerih enaka, zato vse, kar se naučite tukaj, velja za vsako integracijo.

Iz arhitekture, obravnavane v prejšnji lekciji, izhaja ena posledica: ChatKit se izriše znotraj iframe, zato vaša slogovna predloga ne more doseči njegove vsebine. Vaša pravila CSS veljajo samo za vsebnik – velikost in položaj, ki ju dodelite elementu <ChatKit className="…" />. Vse ostalo konfigurirate prek možnosti. To je dobra novica za vzdrževanje: posodobitev ChatKita ne more pokvariti selektorjev CSS, ki ne obstajajo.

Če želite možnosti preizkusiti brez pisanja kode, igrišče ChatKit Studio prikaže izris v živo.

Tema

Tema nadzira splošen videz: barvno shemo, poudarjeno barvo, zaobljenost robov, gostoto in tipografijo.

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 },
  },
});

Vsaka nastavitev ima zaprt nabor vrednosti, ki jih za vas preveri TypeScript:

MožnostVrednostiUčinek
colorScheme'light', 'dark'Svetla (privzeto) ali temna tema
color.accentprimary (hex, rgb(), hsl()…), level od 0 do 3Poudarjena barva vmesnika in intenziveta palete
color.grayscalehue v stopinjah, tint od 0 do 9, shade od −4 do 4Odtenek in senca sive palete
color.surfacebackground, foregroundBarve površin: ozadje in ospredje (besedilo, ikone)
radius'pill', 'round', 'soft', 'sharp'Zaobljenost robov za oblačke, gumbe in polja
density'compact', 'normal', 'spacious'Splošni razmiki
typographyfontFamily, fontFamilyMono, baseSize (14 do 18), fontSourcesPisave in osnovna velikost; fontSources naloži spletno pisavo (family, src, weight…)

Če želite upoštevati uporabnikove nastavitve, izberite shemo ob gradnji možnosti, na primer z window.matchMedia('(prefers-color-scheme: dark)').matches. Sprejeta je tudi tema, reducirana na niz, theme: 'dark', kadar morate nastaviti le barvno shemo.

Začetni zaslon

Prazna nit je lahko zastrašujoča. Začetni zaslon jo nadomesti s pozdravom in predlogi, ki uporabniku pokažejo, kaj asistent zmore:

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 je besedilo gumba, prompt je sporočilo, poslano ob kliku uporabnika, icon pa ime s seznama ikon ChatKita (search, write, calendar, lightbulb…) ali ikona Lucide v obliki 'lucide:name'.

Sestavljalec sporočil

Objekt composer konfigurira nadomestno besedilo, orodja, ponujena uporabniku, in priloge:

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'] },
  },
},

Orodje, izbrano iz menija, se pošlje strežniku kot nastavitev orodja za naslednji krog; to morate upoštevati v svojem agentu.

Priloge so privzeto onemogočene, njihovo omogočanje pa zahteva delo na strani strežnika. Z lastnim strežnikom morate v api določiti tudi način nalaganja datotek: uploadStrategy: { type: 'direct', uploadUrl: '…' } (vmesnik objavi datoteko na vašo končno točko) ali { type: 'two_phase' } (zahteva podpisani URL, nato pa naloži datoteko v vaše shrambo). Na strani Pythona nato zagotovite AttachmentStore. Dokler ta cevovod ne obstaja, ne obkljukajte enabled: true.

Glava, zgodovina in odgovori

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 prikaže fiksni naslov (sicer trenutni naslov niti) in do dva prilagojena gumba, leftAction in rightAction, vsak z ikono v glavi (settings-cog, home…) in funkcijo. header: { enabled: false } skrije celotno glavo, ko vaša aplikacija že zagotavlja svojo vrstico.
  • history omogoči ploščo preteklih pogovorov, z možnostjo preimenovanja in brisanja ali brez. Onemogočite jo, kadar koncept niti za vaš primer uporabe nima smisla, na primer za asistenta za podporo brez uporabniških računov.
  • threadItemActions.feedback prikaže gumba s palcem gor in dol pod odgovori. Vsak klik prispe na vaš strežnik v metodi add_feedback vašega ChatKitServer (thread_id, item_ids, feedback nastavljen na 'positive' ali 'negative'). To je surovina za vaša evalvacijo. retry doda gumb za ponovno generiranje odgovora.
  • disclaimer prikaže kratko besedilo Markdown pod sestavljalcem.

Jezik

ChatKit privzeto uporablja jezik brskalnika. Če ima vaša aplikacija lastno nastavitev jezika, jo vsilite z locale: 'en' ali regionalno različico, kot sta 'en-US' ali 'en-GB'. Vsaka zahteva, poslana vašemu strežniku, nosi ta jezik v glavi Accept-Language: uporabite ga, da agent odgovori in da prevedete sporočila svojih orodij v istem jeziku kot vmesnik.

Vse skupaj

Tukaj je popolna konfiguracija, ki se kot taka kompilira s paketom @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" />;
}

Ključne ugotovitve

  • Vse prilagoditve potekajo prek enotnega objekta z možnostmi, ki je enak v Reactu (useChatKit) in pri spletnem elementu (setOptions)
  • ChatKit se izriše v iframe: vaš CSS oblikuje le vsebnik; vse ostalo poteka prek theme
  • theme: colorScheme, color.accent, radius, density, typography z zaprtimi vrednostmi, ki jih preveri TypeScript
  • startScreen (pozdrav in predlogi), composer (nadomestno besedilo, orodja, priloge), header, history, threadItemActions, disclaimer in locale dopolnjujejo vmesnik
  • Priloge in uporabniške povratne informacije zahtevajo podporo na strani strežnika: uploadStrategy in AttachmentStore ter metoda add_feedback