在完成 ChatKit 快速入门后，了解如何更改主题并将自定义项添加到您的聊天嵌入中。通过浅色和深色主题、设置强调色、控制密度以及圆角效果，来匹配您的应用美学。
概述
从宏观层面看，通过传入一个选项对象来自定义主题。如果您已按照 ChatKit 快速入门将 ChatKit 嵌入到前端，请使用下方的 React 语法。
- React: 将选项传递给
useChatKit({...}) - 高级集成: 使用
chatkit.setOptions({...})设置选项
在这两种集成方式中，选项对象的结构是一致的。
探索自定义选项
访问 ChatKit Studio 查看 ChatKit 的实际实现效果和交互式构建器。如果您喜欢通过实践而非阅读来学习，这些资源是一个很好的起点。
探索 ChatKit UI
体验 ChatKit 的交互式演示。
浏览可用的小组件。
通过交互式演示以在实践中学习。
查看工作示例
查看 ChatKit 的实际示例以获取灵感。
克隆存储库，从功能完备的模板开始构建。
更改主题
通过指定颜色、排版等来匹配您产品的外观和感觉。在下文中，我们设置了深色模式、更改了颜色、设置了圆角、调整了信息密度并设置了字体。
有关所有主题选项，请参阅 API 参考文档。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const options: Partial<ChatKitOptions> = {
theme: {
colorScheme: "dark",
color: {
accent: {
primary: "#2D8CFF",
level: 2
}
},
radius: "round",
density: "compact",
typography: { fontFamily: "'Inter', sans-serif" },
},
};自定义开始屏幕文本
通过更改输入框的占位符文本，让用户知道该问什么或引导他们的首次输入。
1
2
3
4
5
6
7
8
const options: Partial<ChatKitOptions> = {
composer: {
placeholder: "Ask anything about your data…",
},
startScreen: {
greeting: "Welcome to FeedbackBot!",
},
};为新会话显示入门提示
通过在开始对话时建议提示想法，引导用户了解该问什么或做什么。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const options: Partial<ChatKitOptions> = {
startScreen: {
greeting: "What can I help you build today?",
prompts: [
{
name: "Check on the status of a ticket",
prompt: "Can you help me check on the status of a ticket?",
icon: "search"
},
{
name: "Create Ticket",
prompt: "Can you help me create a new support ticket?",
icon: "write"
},
],
},
};在头部添加自定义按钮
自定义头部按钮有助于您添加与集成相关的导航、上下文或操作。
1
2
3
4
5
6
7
8
9
10
11
12
const options: Partial<ChatKitOptions> = {
header: {
customButtonLeft: {
icon: "settings-cog",
onClick: () => openProfileSettings(),
},
customButtonRight: {
icon: "home",
onClick: () => openHomePage(),
},
},
};启用文件附件
附件功能默认处于禁用状态。要启用它，请添加附件配置。除非您使用的是自定义后端，否则必须使用 hosted（托管）上传策略。请参阅 Python SDK 文档以了解更多关于如何与其他上传策略配合自定义后端的信息。
您还可以控制用户可以附加到消息的文件数量、大小和类型。
1
2
3
4
5
6
7
8
9
10
const options: Partial<ChatKitOptions> = {
composer: {
attachments: {
uploadStrategy: { type: 'hosted' },
maxSize: 20 * 1024 * 1024, // 20MB per file
maxCount: 3,
accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },
},
},
}在输入框中通过实体标签启用 @提及
允许用户通过 @提及来标记自定义“实体”。这能够实现更丰富的对话上下文和交互性。
- 使用
onTagSearch根据输入查询返回实体列表。 - 使用
onClick处理实体的点击事件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const options: Partial<ChatKitOptions> = {
entities: {
async onTagSearch(query) {
return [
{
id: "user_123",
title: "Jane Doe",
group: "People",
interactive: true,
},
{
id: "document_123",
title: "Quarterly Plan",
group: "Documents",
interactive: true,
},
]
},
onClick: (entity) => {
navigateToEntity(entity.id);
},
},
};自定义实体标签的显示方式
您可以使用小组件自定义实体标签在鼠标悬停时的外观。当用户将鼠标悬停在实体标签上时，显示丰富的预览，例如名片、文档摘要或图像。
浏览可用的小组件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const options: Partial<ChatKitOptions> = {
entities: {
async onTagSearch() { /* ... */ },
onRequestPreview: async (entity) => ({
preview: {
type: "Card",
children: [
{ type: "Text", value: `Profile: ${entity.title}` },
{ type: "Text", value: "Role: Developer" },
],
},
}),
},
};在输入框中添加自定义工具
通过允许用户从输入栏触发特定于应用的操作来提高工作效率。选定的工具将作为工具偏好发送给模型。
1
2
3
4
5
6
7
8
9
10
11
12
const options: Partial<ChatKitOptions> = {
composer: {
tools: [
{
id: 'add-note',
label: 'Add Note',
icon: 'write',
pinned: true,
},
],
},
};切换 UI 区域和功能
如果您需要对头部可用的选项进行更深入的自定义并希望实现自己的版本，可以禁用主要的 UI 区域和功能。在会话和历史记录的概念对您的用例（例如支持聊天机器人）没有意义时，禁用历史记录会很有用。
1
2
3
4
const options: Partial<ChatKitOptions> = {
history: { enabled: false },
header: { enabled: false },
};覆盖区域设置
如果您有应用范围的语言设置，可以覆盖默认的区域设置。默认情况下，区域设置被设定为浏览器的区域设置。
1
2
3
const options: Partial<ChatKitOptions> = {
locale: 'de-DE',
};