完成 ChatKit 快速入门后,您可以进一步了解如何更改主题并自定义嵌入的聊天界面。选择浅色或深色主题,设置强调色,调整信息密度和圆角,即可让聊天界面与应用的视觉风格保持一致。
概览
要自定义主题,您可以传入一个配置选项对象。如果您已按照 ChatKit 快速入门将 ChatKit 嵌入前端,请使用下面的 React 写法。
- React:将配置选项传给
useChatKit({...}) - 高级集成:使用
chatkit.setOptions({...})设置配置选项
两种集成方式使用的配置选项对象结构相同。
探索自定义选项
访问 ChatKit Studio,查看可运行的 ChatKit 示例并试用交互式构建工具。如果您更喜欢动手尝试,可以从这些资源入手。
探索 ChatKit 界面
体验 ChatKit 交互式演示。
浏览可用的小组件。
试用交互式演示,边操作边学习。
查看可运行的示例
查看可运行的 ChatKit 示例,从中获取灵感。
克隆代码仓库,即可从一个完整可运行的模板开始开发。
更改主题
您可以设置颜色、排版等选项,让聊天界面与产品风格保持一致。下面的示例启用深色模式、更改颜色、设置圆角、调整信息密度并指定字体。
有关全部主题选项,请参阅 API 参考。
import type { ChatKitOptions } from "@openai/chatkit";
const options: Partial<ChatKitOptions> = {
theme: {
colorScheme: "dark",
color: {
accent: {
primary: "#2D8CFF",
level: 2,
},
},
radius: "round",
density: "compact",
typography: { fontFamily: "'Inter', sans-serif" },
},
};自定义起始界面文本
您可以更改消息输入框中的占位文本,让用户知道可以问什么,或引导他们输入第一条消息。
const options: Partial<ChatKitOptions> = {
composer: {
placeholder: "Ask anything about your data…",
},
startScreen: {
greeting: "Welcome to FeedbackBot!",
},
};为新对话显示起始提示词
在对话开始时推荐提示词,让用户了解可以提出哪些问题或执行哪些操作。
const options: Partial<ChatKitOptions> = {
startScreen: {
greeting: "What can I help you build today?",
prompts: [
{
label: "Check on the status of a ticket",
prompt: "Can you help me check on the status of a ticket?",
icon: "search",
},
{
label: "Create Ticket",
prompt: "Can you help me create a new support ticket?",
icon: "write",
},
],
},
};在顶部栏添加自定义按钮
您可以通过顶部栏的自定义按钮提供导航入口、上下文信息或与您的集成相关的操作。
const options: Partial<ChatKitOptions> = {
header: {
leftAction: {
icon: "settings-cog",
onClick: () => openProfileSettings(),
},
rightAction: {
icon: "home",
onClick: () => openHomePage(),
},
},
};启用文件附件
附件默认处于禁用状态。要启用附件,请添加附件配置。
除非您使用自定义后端,否则必须使用 hosted 上传策略。
如需了解如何在自定义后端使用其他上传策略,请参阅 Python SDK 文档。
您还可以限制用户在消息中附加的文件数量、大小和类型。
const options: Partial<ChatKitOptions> = {
composer: {
attachments: {
enabled: true,
maxSize: 20 * 1024 * 1024, // 20 MB per file
maxCount: 3,
accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },
},
},
};使用实体标签在消息输入框中启用 @提及
用户可以通过 @提及来标记自定义“实体”,为对话提供更丰富的上下文和交互方式。
- 使用
onTagSearch根据用户输入的查询返回实体列表。 - 使用
onClick处理实体的点击事件。
const options: Partial<ChatKitOptions> = {
entities: {
async onTagSearch(query) {
void 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);
},
},
};自定义实体标签的显示方式
您可以使用小组件自定义鼠标悬停在实体标签上时显示的内容。例如,用户将鼠标指针移到标签上时,可以看到名片、文档摘要或图像等预览。
浏览可用的小组件。
const options: Partial<ChatKitOptions> = {
entities: {
async onTagSearch() {
return [];
},
onRequestPreview: async (entity) => ({
preview: {
type: "Basic",
children: [
{ type: "Text", value: `Profile: ${entity.title}` },
{ type: "Text", value: "Role: Developer" },
],
},
}),
},
};在消息输入框中添加自定义工具
让用户从消息输入栏触发应用特有的操作,提高使用效率。系统会将用户选中的工具作为工具偏好发送给模型。
const options: Partial<ChatKitOptions> = {
composer: {
tools: [
{
id: "add-note",
label: "Add Note",
icon: "write",
pinned: true,
},
],
},
};启用或禁用界面区域和功能
如果您需要进一步自定义顶部栏中的选项,并希望自行实现这些选项,可以禁用主要界面区域和功能。如果您的使用场景无需区分不同对话或查看历史记录(例如客服聊天机器人),可以禁用历史记录。
const options: Partial<ChatKitOptions> = {
history: { enabled: false },
header: { enabled: false },
};覆盖默认区域设置
如果您的应用有统一的语言设置,可以用它覆盖默认区域设置。默认情况下,ChatKit 使用浏览器的区域设置。
const options: Partial<ChatKitOptions> = {
locale: "de-DE",
};