如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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" },
        ],
      },
    }),
  },
};

在訊息輸入框中新增自訂工具

讓使用者直接從訊息輸入列觸發應用程式特有的操作,提高工作效率。ChatKit 會將使用者選取的工具作為工具偏好設定傳送給模型。

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",
};