Témák és testreszabás
Ezen az oldalon
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/chatkit1.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(nemname) a kezdőképernyő javaslatainál, valamintleftActionésrightAction(nemcustomButtonLeftéscustomButtonRight) a fejléc gombjainál. Források: Témák és testreszabás a ChatKitben ·ChatKitOptionsreferencia · 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ékek | Hatás |
|---|---|---|
colorScheme | 'light', 'dark' | Világos (alapértelmezett) vagy sötét téma |
color.accent | primary (hex, rgb(), hsl()…), level 0-tól 3-ig | A felület kiemelő színe és a paletta intenzitása |
color.grayscale | hue fokban, tint 0-tól 9-ig, shade −4-től 4-ig | A szürke paletta árnyalata és telítettsége |
color.surface | background, foreground | Felü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 |
typography | fontFamily, fontFamilyMono, baseSize (14–18), fontSources | Betű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
headeregy 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ésrightAction. Mindkettőhöz tartozik egy fejlécikon (settings-cog,home…) és egy függvény. Aheader: { enabled: false }elrejti az egész fejlécet, ha az alkalmazásod már biztosít saját sávot. - A
historyengedé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.feedbackthumbs-up és thumbs-down gombokat jelenít meg a válaszok alatt. Minden kattintás eljut a szerveredre aChatKitServerosztályadd_feedbackmetódusában (thread_id,item_ids,feedbackértéke'positive'vagy'negative'). Ez a nyers anyag az értékeléseidhez. Aretryhozzáadja a válasz újragenerálására szolgáló gombot. - A
disclaimeregy 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
themeobjektumon 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éslocaleteszik teljessé a felületet - A csatolmányok és a felhasználói visszajelzések szerveroldali támogatást igényelnek:
uploadStrategyésAttachmentStore, valamint azadd_feedbackmetódus