如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

ChatKit 主题设置与自定义

配置颜色、排版、信息密度和组件变体。

完成 ChatKit 快速入门后,您可以进一步了解如何更改主题并自定义嵌入的聊天界面。选择浅色或深色主题,设置强调色,调整信息密度和圆角,即可让聊天界面与应用的视觉风格保持一致。

概览

要自定义主题,您可以传入一个配置选项对象。如果您已按照 ChatKit 快速入门将 ChatKit 嵌入前端,请使用下面的 React 写法。

  • React:将配置选项传给 useChatKit({...})
  • 高级集成:使用 chatkit.setOptions({...}) 设置配置选项

两种集成方式使用的配置选项对象结构相同。

探索自定义选项

访问 ChatKit Studio,查看可运行的 ChatKit 示例并试用交互式构建工具。如果您更喜欢动手尝试,可以从这些资源入手。

探索 ChatKit 界面

chatkit.world

体验 ChatKit 交互式演示。

小组件构建器

浏览可用的小组件。

ChatKit Playground

试用交互式演示,边操作边学习。

查看可运行的示例

GitHub 上的示例

查看可运行的 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",
};