API 参考

了解以编程方式使用 Docs Embed 时可用的方法

Docs Embed 根据你的集成方式提供不同的 API。本参考文档涵盖所有集成方式中可用的全部方法。

方法对比

方法	独立脚本	NPM 包	React 组件
初始化	GitBook('init', options, frameOptions)	createGitBook(options)	<GitBookProvider siteURL="...">
获取 frame URL	❌（由内部处理）	client.getFrameURL(options)	useGitBook().getFrameURL(options)
创建 frame 客户端	❌（由内部处理）	client.createFrame(iframe)	useGitBook().createFrame(iframe)
显示/隐藏小部件	GitBook('show') / GitBook('hide')	❌	❌
打开/关闭窗口	GitBook('open') / GitBook('close') / GitBook('toggle')	❌	❌
导航到页面	GitBook('navigateToPage', path)	frame.navigateToPage(path)	通过 frame 客户端
导航到助手	GitBook('navigateToAssistant')	frame.navigateToAssistant()	通过 frame 客户端
发送消息	GitBook('postUserMessage', message)	frame.postUserMessage(message)	通过 frame 客户端
清除聊天	GitBook('clearChat')	frame.clearChat()	通过 frame 客户端
配置	GitBook('configure', settings)	frame.configure(settings)	属性在 <GitBookFrame>
事件监听器	❌	frame.on(event, listener)	通过 frame 客户端
卸载	GitBook('unload')	❌	❌

独立脚本 API

初始化

GitBook('init', options, frameOptions)

使用站点 URL 和可选的已认证访问来初始化小部件。

参数：

• options: { siteURL: string } - 你的 GitBook 文档站点 URL

• frameOptions: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } } （可选）- 已认证访问选项

示例：

window.GitBook('init', 
  { siteURL: 'https://docs.company.com' },
  { visitor: { token: 'your-jwt-token' } }
);

小部件控制

显示小部件

如果 GitBook 小部件已被隐藏，则将其显示出来。

示例：

window.GitBook("show");

隐藏小部件

隐藏 GitBook 小部件，但不卸载它。

示例：

window.GitBook("hide");

打开窗口

打开 Docs Embed 窗口。

示例：

window.GitBook("open");

关闭窗口

关闭 Docs Embed 窗口。

示例：

window.GitBook("close");

切换窗口

切换 Docs Embed 窗口的打开或关闭状态。

示例：

window.GitBook("toggle");

卸载小部件

从你的网站中完全移除 GitBook 小部件。

示例：

window.GitBook("unload");

导航

GitBook('navigateToPage', path)

根据路径导航到 GitBook 文档中的特定页面。

参数：

• path （字符串）：你要导航到的页面路径

示例：

// 导航到入门指南
window.GitBook("navigateToPage", "/getting-started");

// 导航到特定的 API 文档页面
window.GitBook("navigateToPage", "/api/authentication");

// 导航到 FAQ 部分
window.GitBook("navigateToPage", "/faq/billing");

GitBook('navigateToAssistant')

直接导航到助手标签页。

示例：

// 切换到助手标签页
window.GitBook("navigateToAssistant");

// 你可以在响应按钮点击时使用它
document.getElementById("help-button").addEventListener("click", () => {
  window.GitBook("navigateToAssistant");
});

聊天

GitBook('postUserMessage', message)

像用户输入的一样向聊天中发送一条消息。

参数：

• message （字符串）：要发送到聊天中的消息

示例：

// 发送预设消息
window.GitBook("postUserMessage", "How do I reset my password?");

// 根据用户操作发送消息
function askAboutBilling() {
  window.GitBook("postUserMessage", "I have questions about my billing");
}

// 发送带有上下文的消息
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `我正在使用 ${userPlan} 套餐，需要高级功能方面的帮助`
);

GitBook('clearChat')

清除当前聊天会话中的所有消息。

示例：

// 清除聊天
window.GitBook("clearChat");

// 清除聊天并开始新的对话
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "Hello, I need help with a new issue");
}

// 在切换上下文时清除聊天
document.getElementById("new-topic").addEventListener("click", () => {
  window.GitBook("clearChat");
  window.GitBook("navigateToAssistant");
});

配置

GitBook('configure', settings)

使用自定义选项配置嵌入。请参见 配置部分 以了解可用选项。

示例：

window.GitBook('configure', {
  trademark: false,
  tabs: ['assistant', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: '联系支持',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: '欢迎！', subtitle: '我能为你做什么？' },
  suggestions: ['什么是 GitBook？', '我该如何开始？']
});

NPM 包 API

客户端工厂

createGitBook(options)

创建一个 GitBook 客户端实例。

参数：

• options: { siteURL: string } - 你的 GitBook 文档站点 URL

返回： GitBookClient

示例：

import { createGitBook } from '@gitbook/embed';

const gitbook = createGitBook({
  siteURL: 'https://docs.company.com'
});

client.getFrameURL(options)

获取带有可选已认证访问的 iframe URL。

参数：

• options: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } } （可选）

返回： 字符串

示例：

const iframeURL = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token',
    unsignedClaims: { userId: '123', plan: 'premium' }
  }
});

client.createFrame(iframe)

创建一个 frame 客户端以与 iframe 通信。

参数：

• iframe: HTMLIFrameElement - iframe 元素

返回： GitBookFrameClient

示例：

const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL();
const frame = gitbook.createFrame(iframe);

Frame 客户端方法

frame.navigateToPage(path)

导航到 docs 标签页中的特定页面。

参数：

• path: 字符串 - 页面路径

frame.navigateToAssistant()

切换到助手标签页。

frame.postUserMessage(message)

向聊天中发送一条消息。

参数：

• message: 字符串 - 要发送的消息

frame.clearChat()

清除聊天历史。

frame.configure(settings)

配置嵌入。请参见 配置部分 以了解可用选项。

frame.on(event, listener)

注册事件监听器。

参数：

• event: 字符串 - 事件名称

• listener: 函数 - 回调函数

返回： () => void - 取消订阅函数

示例：

const unsubscribe = frame.on('close', () => {
  console.log('Frame 已关闭');
});

// 稍后取消订阅
unsubscribe();

React 组件 API

请参见 React 集成指南 了解组件属性以及 useGitBook hook API。