Tematizzazzjoni u personalizzazzjoni
F'din il-paġna
Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddependi fuq komponenti u għażliet li ma jeżistux f’ChatKit:
ChatProvider,MessageInput, rendering personalizzat tal-messaġġi, u fogli tal-istil injettati. Issa ssegwi l-gwida Theming and customization ta’ OpenAI u t-tipi minn@openai/chatkit1.9.0; l-eżempju sħiħ ġie vverifikat permezz tal-kompilazzjoni ta’ TypeScript. Żewġ ismijiet ivarjaw bejn il-gwida u l-pakkett ippubblikat, u din il-lezzjoni ssegwi l-pakkett:label(mhuxname) għas-suġġerimenti tal-iskrin tal-bidu, uleftActionurightAction(mhuxcustomButtonLeftucustomButtonRight) għall-buttuni tal-intestatura. Sorsi: Theming and customization in ChatKit ·ChatKitOptionsreference · ChatKit Studio.
Oġġett wieħed ta’ għażliet
Il-personalizzazzjoni kollha ta’ ChatKit issir permezz ta’ oġġett wieħed ta’ għażliet. F’React, tgħaddih lil useChatKit({...}); bil-komponent web, lil chatkit.setOptions({...}). L-istruttura hija identika fiż-żewġ każijiet, allura dak li titgħallem hawnhekk japplika għal kull integrazzjoni.
Konsegwenza waħda ssegwi mill-arkitettura koperta fil-lezzjoni preċedenti: ChatKit jirrendi ġewwa iframe, allura l-folja tal-istil tiegħek ma tistax tilħaqha. Ir-regoli CSS tiegħek japplikaw biss għall-kontenitur—id-daqs u l-pożizzjoni li tagħti lil <ChatKit className="…" />. Kollox ieħor huwa kkonfigurat permezz tal-għażliet. Din hija aħbar tajba għall-manutenzjoni: aġġornament ta’ ChatKit ma jistax ikisser seletturi CSS li ma jeżistux.
Biex tipprova l-għażliet mingħajr ma tikteb kodiċi, il-ChatKit Studio playground juri r-rendering ħaj.
It-tema
It-tema tikkontrolla d-dehra ġenerali: skema tal-kulur, kulur ta’ aċċent, raġġ tal-kantuniera, densità, u tipografija.
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 },
},
});
Kull setting għandu sett magħluq ta’ valuri, li TypeScript jivvalida għalik:
| Għażla | Valuri | Effett |
|---|---|---|
colorScheme | 'light', 'dark' | Tema ċara (default) jew skura |
color.accent | primary (hex, rgb(), hsl()…), level minn 0 sa 3 | Kulur ta’ aċċent tal-interfaċċa u intensità tal-paletta |
color.grayscale | hue fi gradi, tint minn 0 sa 9, shade minn −4 sa 4 | Lewn u dell tal-paletta griża |
color.surface | background, foreground | Kuluri tal-wiċċ: sfond u quddiem (test, ikoni) |
radius | 'pill', 'round', 'soft', 'sharp' | Raġġ tal-kantuniera għal bżieżaq, buttuni, u oqsma |
density | 'compact', 'normal', 'spacious' | Spazjar ġenerali |
typography | fontFamily, fontFamilyMono, baseSize (14 sa 18), fontSources | Fonts u daqs bażiku; fontSources ittagħbija web font (family, src, weight…) |
Biex issegwi l-preferenza tal-utent, agħżel l-iskema meta tibni l-għażliet, pereżempju b’window.matchMedia('(prefers-color-scheme: dark)').matches. theme imnaqqas għal stringa, theme: 'dark', huwa aċċettat ukoll meta trid biss tissettja l-iskema tal-kulur.
L-iskrin tal-bidu
Thread vojt jista’ jkun intimidatorju. L-iskrin tal-bidu jissostitwixxih b’tislima u suġġerimenti li juru lill-utent x’jista’ jagħmel l-assistent:
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 huwa t-test tal-buttuna, prompt huwa l-messaġġ mibgħut meta l-utent jikklikkja, u icon huwa isem mil-lista tal-ikoni ta’ ChatKit (search, write, calendar, lightbulb…), jew ikona Lucide fil-forma 'lucide:name'.
Il-kompożitur
L-oġġett composer jikkonfigura t-test tal-placeholder, l-għodod offruti lill-utent, u l-attachments:
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'] },
},
},
L-għodda magħżula mill-menu tintbagħat lis-server bħala preferenza tal-għodda għad-dawra li jmiss; trid tikkontaha fl-aġent tiegħek.
L-attachments huma diżattivati b’mod default, u biex tattivahom jeħtieġ xogħol fuq in-naħa tas-server. Bis-server tiegħek stess, trid tispeċifika wkoll f’api kif jitilgħu l-fajls: uploadStrategy: { type: 'direct', uploadUrl: '…' } (l-interfaċċa tippostja l-fajl fl-endpoint tiegħek) jew { type: 'two_phase' } (titlob URL iffirmat, imbagħad ittellgħa l-fajl fil-ħażna tiegħek). Fuq in-naħa ta’ Python, imbagħad tipprovdi AttachmentStore. Tikkontrollax enabled: true sakemm dan il-pipeline ma jeżistix.
Intestatura, storja, u tweġibiet
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)" },
headerjuri titolu fiss (inkella t-titolu kurrenti tat-thread) u sa żewġ buttuni personalizzati,leftActionurightAction, kull waħda b’ikona tal-intestatura (settings-cog,home…) u funzjoni.header: { enabled: false }taħbi l-intestatura kollha meta l-applikazzjoni tiegħek diġà tipprovdi l-barra tagħha stess.historyjattiva l-pannell tal-konversazzjonijiet tal-passat, bir-rieda jew mingħajr ibdil tal-isem u tħassir. Iddiżattivah meta l-kunċett ta’ thread ma jagħmilx sens għall-każ ta’ użu tiegħek, pereżempju għal assistent ta’ appoġġ mingħajr kontijiet tal-utenti.threadItemActions.feedbackjuri buttuni ta’ swaba’ ‘l fuq u ‘l isfel taħt it-tweġibiet. Kull klikk jasal għand is-server tiegħek fil-metoduadd_feedbackta’ChatKitServertiegħek (thread_id,item_ids,feedbackissettjat għal'positive'jew'negative'). Dan huwa l-materja prima għall-evalwazzjonijiet tiegħek.retryiżid il-buttuna li tiġġenera mill-ġdid tweġiba.disclaimerjuri test qasir ta’ Markdown taħt il-kompożitur.
Lingwa
B’mod default, ChatKit juża l-lingwa tal-browser. Jekk l-applikazzjoni tiegħek għandha s-setting tal-lingwa tagħha stess, infurzaha b’locale: 'en', jew varjant reġjonali bħal 'en-US' jew 'en-GB'. Kull talba mibgħuta lis-server tiegħek iġġorr din il-lingwa fl-header Accept-Language: użaha biex l-aġent iwieġeb u biex tittraduċi l-messaġġi tal-għodda tiegħek fl-istess lingwa tal-interfaċċa.
Ngħaqqdu kollox flimkien
Hawnhekk hemm konfigurazzjoni sħiħa, ikkompilata hekk kif inhi b’@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" />;
}
Punti Ewlenin
- Il-personalizzazzjoni kollha ssir permezz ta’ oġġett wieħed ta’ għażliet, identiku f’React (
useChatKit) u bil-komponent web (setOptions) - ChatKit jirrendi f’iframe: il-CSS tiegħek jistilja biss il-kontenitur; kollox ieħor jgħaddi minn
theme theme:colorScheme,color.accent,radius,density,typography, b’valuri magħluqa vvalidati minn TypeScriptstartScreen(tislima u suġġerimenti),composer(placeholder, għodod, attachments),header,history,threadItemActions,disclaimer, ulocalejikkompletaw l-interfaċċa- L-attachments u l-feedback tal-utent jeħtieġu appoġġ fuq in-naħa tas-server:
uploadStrategyuAttachmentStore, flimkien mal-metoduadd_feedback