Премини към основното съдържание
Български— Изберете език
Меню

Темизиране и персонализиране

Урок 18 от 25 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Един единствен обект с опции
  2. Темата
  3. Началният екран
  4. Композиторът
  5. Заглавка, история и отговори
  6. Език
  7. Събиране на всичко заедно
  8. Ключови изводи

Урокът е пренаписан на 3 ноември 2026 г. Предишната версия разчиташе на компоненти и опции, които не съществуват в ChatKit: ChatProvider, MessageInput, персонализиран рендеринг на съобщения и инжектирани таблици със стилове. Сега той следва ръководството на OpenAI Темизиране и персонализиране и типовете от @openai/chatkit 1.9.0; пълният пример е верифициран чрез компилация на TypeScript. Две имена се различават между ръководството и публикувания пакет, като този урок следва пакета: label (не name) за предложенията на началния екран и leftAction и rightAction (не customButtonLeft и customButtonRight) за бутоните в заглавката. Източници: Темизиране и персонализиране в ChatKit · ChatKitOptions референция · ChatKit Studio.

Един единствен обект с опции

Цялото персонализиране на ChatKit става чрез един единствен обект с опции. В React го предавате на useChatKit({...}); с уеб компонента – на chatkit.setOptions({...}). Структурата е идентична и в двата случая, така че наученото тук важи за всяка интеграция.

От архитектурата, разгледана в предишния урок, следва едно следствие: ChatKit се рендерира вътре в iframe, така че Вашата таблица със стилове не може да достигне до него. Вашите CSS правила се прилагат само към контейнера – размера и позицията, които задавате на <ChatKit className="…" />. Всичко останало се конфигурира чрез опции. Това е добра новина за поддръжката: актуализация на ChatKit не може да счупи CSS селектори, които не съществуват.

За да изпробвате опциите без писане на код, ChatKit Studio playground показва рендериране на живо.

Темата

Темата контролира общия външен вид: цветова схема, акцентен цвят, радиус на ъглите, плътност и типография.

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

Всяка настройка има затворен набор от стойности, които TypeScript валидира за Вас:

ОпцияСтойностиЕфект
colorScheme'light', 'dark'Светла (по подразбиране) или тъмна тема
color.accentprimary (hex, rgb(), hsl()…), level от 0 до 3Акцентен цвят на интерфейса и интензитет на палитрата
color.grayscalehue в градуси, tint от 0 до 9, shade от −4 до 4Нюанс и сянка на сивата палитра
color.surfacebackground, foregroundЦветове на повърхността: фон и преден план (текст, икони)
radius'pill', 'round', 'soft', 'sharp'Радиус на ъглите за балончета, бутони и полета
density'compact', 'normal', 'spacious'Общо разстояние между елементите
typographyfontFamily, fontFamilyMono, baseSize (14 до 18), fontSourcesШрифтове и основен размер; fontSources зарежда уеб шрифт (family, src, weight…)

За да следвате предпочитанията на потребителя, изберете схемата при изграждането на опциите, например с window.matchMedia('(prefers-color-scheme: dark)').matches. Приема се и theme, сведен до низ, theme: 'dark', когато трябва да зададете само цветовата схема.

Началният екран

Една празна нишка може да изглежда плашеща. Началният екран я заменя с поздрав и предложения, които показват на потребителя какво може да прави асистентът:

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 е текстът на бутона, prompt е съобщението, изпратено при кликване от потребителя, а icon е име от списъка с икони на ChatKit (search, write, calendar, lightbulb…) или икона на Lucide във формата 'lucide:name'.

Композиторът

Обектът composer конфигурира текста на подсказката, инструментите, предлагани на потребителя, и прикачените файлове:

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

Инструментът, избран от менюто, се изпраща на сървъра като предпочитание за инструмент за следващия ход; трябва да го отчетете във Вашия агент.

Прикачените файлове са деактивирани по подразбиране и активирането им изисква работа от страна на сървъра. със собствен сървър трябва също да посочите в api как се качват файловете: uploadStrategy: { type: 'direct', uploadUrl: '…' } (интерфейсът публикува файла към Вашата крайна точка) или { type: 'two_phase' } (той иска подписан URL адрес, след което качва файла във Вашето хранилище). От страната на Python тогава предоставяте AttachmentStore. Не проверявайте enabled: true, докато този конвейер не съществува.

Заглавка, история и отговори

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 показва фиксирано заглавие (в противен случай текущото заглавие на нишката) и до два персонализирани бутона, leftAction и rightAction, всеки с икона в заглавката (settings-cog, home…) и функция. header: { enabled: false } скрива цялата заглавка, когато Вашето приложение вече предоставя собствена лента.
  • history активира панела с минали разговори, с или без преименуване и изтриване. Деактивирайте го, когато концепцията за нишка няма смисъл за Вашия случай на употреба, например за асистент за поддръжка без потребителски акаунти.
  • threadItemActions.feedback показва бутони за палец нагоре и надолу под отговорите. Всеки клик пристига на Вашия сървър в метода add_feedback на Вашия ChatKitServer (thread_id, item_ids, feedback зададен на 'positive' или 'negative'). Това е суровият материал за Вашите оценки. retry добавя бутона, който регенерира отговор.
  • disclaimer показва кратък Markdown текст под композитора.

Език

По подразбиране ChatKit използва езика на браузъра. Ако Вашето приложение има собствена езикова настройка, наложете я с locale: 'en' или регионален вариант като 'en-US' или 'en-GB'. Всяка заявка, изпратена до Вашия сървър, носи този език в заглавката Accept-Language: използвайте го, за да накарате агента да отговори и да преведете съобщенията на Вашите инструменти на същия език като интерфейса.

Събиране на всичко заедно

Ето една пълна конфигурация, компилирана както е с @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" />;
}

Ключови изводи

  • Цялото персонализиране става чрез един единствен обект с опции, идентичен в React (useChatKit) и с уеб компонента (setOptions)
  • ChatKit се рендерира в iframe: Вашето CSS стилизира само контейнера; всичко останало минава през theme
  • theme: colorScheme, color.accent, radius, density, typography, със затворени стойности, валидирани от TypeScript
  • startScreen (поздрав и предложения), composer (подсказка, инструменти, прикачени файлове), header, history, threadItemActions, disclaimer и locale допълват интерфейса
  • Прикачените файлове и потребителската обратна връзка изискват поддръжка от страна на сървъра: uploadStrategy и AttachmentStore, плюс метода add_feedback