在按照 ChatKit 快速入门，了解如何更改主题并为你的聊天嵌入组件添加自定义设置。通过明暗主题匹配你的应用视觉风格，设置强调色、控制密度以及圆角。
概览
从宏观上看，通过传入选项对象来自定义主题。如果你已按照 ChatKit 快速入门 在前端中嵌入 ChatKit，请使用下面的 React 语法。
- React: Pass options to
useChatKit({...}) - 高级集成: Set options with
chatkit.setOptions({...})
无论采用哪种集成方式，选项对象的结构都是相同的。
浏览自定义选项
访问 ChatKit Studio 以查看 ChatKit 的可用实现和交互式构建器。如果你更喜欢动手尝试而非阅读文档，这些资源将是一个很好的起点。
探索 ChatKit UI
体验 ChatKit 交互式演示。
浏览可用的 Widget。
通过交互式演示在实践中学习。
查看实际示例
查看 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);
},
},
};自定义实体标签的显示方式
你可以使用 Widget 自定义鼠标悬停时实体标签的外观。当用户将鼠标悬停在实体标签上时，显示丰富的预览信息，如名片、文档摘要或图像。
浏览可用的 Widget。
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',
};