Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Tematizzazzjoni u personalizzazzjoni

Lezzjoni 18 / 25 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Oġġett wieħed ta’ għażliet
  2. It-tema
  3. L-iskrin tal-bidu
  4. Il-kompożitur
  5. Intestatura, storja, u tweġibiet
  6. Lingwa
  7. Ngħaqqdu kollox flimkien
  8. Punti Ewlenin

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/chatkit 1.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 (mhux name) għas-suġġerimenti tal-iskrin tal-bidu, u leftAction u rightAction (mhux customButtonLeft u customButtonRight) għall-buttuni tal-intestatura. Sorsi: Theming and customization in ChatKit · ChatKitOptions reference · 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żlaValuriEffett
colorScheme'light', 'dark'Tema ċara (default) jew skura
color.accentprimary (hex, rgb(), hsl()…), level minn 0 sa 3Kulur ta’ aċċent tal-interfaċċa u intensità tal-paletta
color.grayscalehue fi gradi, tint minn 0 sa 9, shade minn −4 sa 4Lewn u dell tal-paletta griża
color.surfacebackground, foregroundKuluri 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
typographyfontFamily, fontFamilyMono, baseSize (14 sa 18), fontSourcesFonts 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)" },
  • header juri titolu fiss (inkella t-titolu kurrenti tat-thread) u sa żewġ buttuni personalizzati, leftAction u rightAction, 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.
  • history jattiva 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.feedback juri buttuni ta’ swaba’ ‘l fuq u ‘l isfel taħt it-tweġibiet. Kull klikk jasal għand is-server tiegħek fil-metodu add_feedback ta’ ChatKitServer tiegħek (thread_id, item_ids, feedback issettjat għal 'positive' jew 'negative'). Dan huwa l-materja prima għall-evalwazzjonijiet tiegħek. retry iżid il-buttuna li tiġġenera mill-ġdid tweġiba.
  • disclaimer juri 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 TypeScript
  • startScreen (tislima u suġġerimenti), composer (placeholder, għodod, attachments), header, history, threadItemActions, disclaimer, u locale jikkompletaw l-interfaċċa
  • L-attachments u l-feedback tal-utent jeħtieġu appoġġ fuq in-naħa tas-server: uploadStrategy u AttachmentStore, flimkien mal-metodu add_feedback