Темизиране и персонализиране
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия разчиташе на компоненти и опции, които не съществуват в ChatKit:
ChatProvider,MessageInput, персонализиран рендеринг на съобщения и инжектирани таблици със стилове. Сега той следва ръководството на OpenAI Темизиране и персонализиране и типовете от@openai/chatkit1.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.accent | primary (hex, rgb(), hsl()…), level от 0 до 3 | Акцентен цвят на интерфейса и интензитет на палитрата |
color.grayscale | hue в градуси, tint от 0 до 9, shade от −4 до 4 | Нюанс и сянка на сивата палитра |
color.surface | background, foreground | Цветове на повърхността: фон и преден план (текст, икони) |
radius | 'pill', 'round', 'soft', 'sharp' | Радиус на ъглите за балончета, бутони и полета |
density | 'compact', 'normal', 'spacious' | Общо разстояние между елементите |
typography | fontFamily, 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, със затворени стойности, валидирани от TypeScriptstartScreen(поздрав и предложения),composer(подсказка, инструменти, прикачени файлове),header,history,threadItemActions,disclaimerиlocaleдопълват интерфейса- Прикачените файлове и потребителската обратна връзка изискват поддръжка от страна на сървъра:
uploadStrategyиAttachmentStore, плюс методаadd_feedback