完成 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" },
],
},
}),
},
};在訊息輸入框中新增自訂工具
讓使用者直接從訊息輸入列觸發應用程式特有的操作,提高工作效率。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",
};