Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Témák és testreszabás

18. lecke 25 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Egyetlen beállításobjektum
  2. A téma
  3. A kezdőképernyő
  4. A beviteli mező (Composer)
  5. Fejléc, előzmények és válaszok
  6. Nyelv
  7. Minden együtt
  8. Főbb megállapítások

Lecke átírva: 2026. november 3. Az előző verzió olyan komponensekre és beállításokra támaszkodott, amelyek nem léteznek a ChatKitben: ChatProvider, MessageInput, egyedi üzenetmegjelenítés és beszúrt stíluslapok. Ez a változat már az OpenAI Témák és testreszabás útmutatóját és az @openai/chatkit 1.9.0 típusait követi; a teljes példát TypeScript fordítással ellenőriztük. Két elnevezés eltér az útmutató és a közzétett csomag között; ez a lecke a csomagot követi: label (nem name) a kezdőképernyő javaslatainál, valamint leftAction és rightAction (nem customButtonLeft és customButtonRight) a fejléc gombjainál. Források: Témák és testreszabás a ChatKitben · ChatKitOptions referencia · ChatKit Studio.

Egyetlen beállításobjektum

A ChatKit összes testreszabása egyetlen beállításobjektumon keresztül történik. React esetén ezt a useChatKit({...}) függvénynek adod át; webkomponens használatakor pedig a chatkit.setOptions({...}) metódusnak. A szerkezet mindkét esetben azonos, így amit itt megtanulsz, minden integrációra érvényes.

Ebből az előző leckében tárgyalt architektúrából következően adódik egy fontos következmény: a ChatKit egy iframe-en belül renderelődik, így a saját stíluslapod nem fér hozzá. A CSS-szabályaid csak a konténerre vonatkoznak – arra a méretre és pozícióra, amit a <ChatKit className="…" /> elemnek adsz meg. Minden mást a beállításobjektummal konfigurálsz. Ez karbantartási szempontból jó hír: egy ChatKit-frissítés nem törhet el olyan CSS-kijelölőket, amelyek nem is léteznek.

Ha kódírás nélkül szeretnéd kipróbálni a beállításokat, a ChatKit Studio playground élő előnézetet biztosít.

A téma

A téma a megjelenés egészét vezérli: színsémát, kiemelő színt, sarkok sugarát, sűrűséget és tipográfiát.

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

Minden beállítás zárt értékkészlettel rendelkezik, amit a TypeScript automatikusan ellenőriz:

BeállításÉrtékekHatás
colorScheme'light', 'dark'Világos (alapértelmezett) vagy sötét téma
color.accentprimary (hex, rgb(), hsl()…), level 0-tól 3-igA felület kiemelő színe és a paletta intenzitása
color.grayscalehue fokban, tint 0-tól 9-ig, shade −4-től 4-igA szürke paletta árnyalata és telítettsége
color.surfacebackground, foregroundFelületi színek: háttér és előtér (szöveg, ikonok)
radius'pill', 'round', 'soft', 'sharp'A buborékok, gombok és mezők sarkainak sugara
density'compact', 'normal', 'spacious'Általános térközök
typographyfontFamily, fontFamilyMono, baseSize (14–18), fontSourcesBetűtípusok és alapméret; a fontSources webes betűtípust tölt be (family, src, weight…)

Ha követni szeretnéd a felhasználó preferenciáit, a beállítások összeállításakor válaszd ki a sémát, például így: window.matchMedia('(prefers-color-scheme: dark)').matches. Ha csak a színsémát akarod beállítani, a theme megadható egyszerű szövegként is: theme: 'dark'.

A kezdőképernyő

Egy üres beszélgetésszál ijesztő lehet. A kezdőképernyő ezt váltja fel egy üdvözléssel és javaslatokkal, amelyek megmutatják a felhasználónak, mire képes a segéd:

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

A label a gomb szövege, a prompt az elküldendő üzenet, ha a felhasználó rákattint, az icon pedig a ChatKit ikonlistájából származó név (search, write, calendar, lightbulb…), vagy egy Lucide ikon 'lucide:name' alakban.

A beviteli mező (Composer)

A composer objektum konfigurálja a helykitöltő szöveget, a felhasználó számára elérhető eszközöket és a csatolmányokat:

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 fájlonként
    accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
  },
},

A menüből kiválasztott eszközt a szerver eszközpreferenciaként kapja meg a következő körhöz; ezt az ágensedben kezelned kell.

A csatolmányok alapértelmezetten le vannak tiltva, és engedélyezésükhöz szerveroldali munka szükséges. Saját szerver használata esetén az api szakaszban meg kell adnod a fájlfeltöltés módját is: uploadStrategy: { type: 'direct', uploadUrl: '…' } (a felület közvetlenül a te végpontodra küldi a fájlt) vagy { type: 'two_phase' } (először egy aláírt URL-t kér, majd feltölti a fájlt a tárhelyedre). Python oldalon ehhez egy AttachmentStore-t kell biztosítanod. Ne állítsd az enabled: true értéket, amíg ez a folyamatrendszer nem áll készen.

Fejléc, előzmények és válaszok

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)" },
  • A header egy rögzített címet jelenít meg (egyébként az aktuális szál címét), valamint legfeljebb két egyedi gombot: leftAction és rightAction. Mindkettőhöz tartozik egy fejlécikon (settings-cog, home…) és egy függvény. A header: { enabled: false } elrejti az egész fejlécet, ha az alkalmazásod már biztosít saját sávot.
  • A history engedélyezi a múltbeli beszélgetések paneljét, átnevezési és törlési lehetőséggel vagy anélkül. Kapcsold ki, ha a szál fogalma nincs értelme az esetedben, például felhasználói fiókok nélküli ügyfélszolgálati segéd esetén.
  • A threadItemActions.feedback thumbs-up és thumbs-down gombokat jelenít meg a válaszok alatt. Minden kattintás eljut a szerveredre a ChatKitServer osztály add_feedback metódusában (thread_id, item_ids, feedback értéke 'positive' vagy 'negative'). Ez a nyers anyag az értékeléseidhez. A retry hozzáadja a válasz újragenerálására szolgáló gombot.
  • A disclaimer egy rövid Markdown szöveget jelenít meg a beviteli mező alatt.

Nyelv

Alapértelmezetten a ChatKit a böngésző nyelvét használja. Ha az alkalmazásodnak saját nyelvi beállítása van, kényszerítsd ki a locale: 'en' beállítással, vagy egy regionális változattal, mint például 'en-US' vagy 'en-GB'. A szervered felé küldött minden kérés tartalmazza ezt a nyelvet az Accept-Language fejlécben: használd ezt arra, hogy az ágens ugyanazon a nyelven válaszoljon, és hogy az eszközüzeneteidet is a felület nyelvén fordítsd le.

Minden együtt

Íme egy teljes konfiguráció, amely változtatás nélkül lefordítható az @openai/chatkit-react 1.6.1 verzióval:

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" />;
}

Főbb megállapítások

  • Minden testreszabás egyetlen beállításobjektumon keresztül történik, amely azonos Reactben (useChatKit) és a webkomponens esetén is (setOptions)
  • A ChatKit iframe-ben renderelődik: a CSS-ed csak a konténert stilizálja; minden más a theme objektumon keresztül történik
  • theme: colorScheme, color.accent, radius, density, typography, zárt értékkészletekkel, amelyeket a TypeScript ellenőriz
  • A startScreen (üdvözlés és javaslatok), composer (helykitöltő, eszközök, csatolmányok), header, history, threadItemActions, disclaimer és locale teszik teljessé a felületet
  • A csatolmányok és a felhasználói visszajelzések szerveroldali támogatást igényelnek: uploadStrategy és AttachmentStore, valamint az add_feedback metódus