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)	Props 在 <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 (string)：你要导航到的页面路径

示例：

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

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

// 导航到常见问题部分
window.GitBook("navigateToPage", "/faq/billing");

GitBook('navigateToAssistant')

直接切换到 Assistant 选项卡。

示例：

// 切换到助手选项卡
window.GitBook("navigateToAssistant");

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

聊天

GitBook('postUserMessage', message)

将消息发布到聊天，就像用户输入的一样。

参数：

• message (string)：要发布到聊天的消息

示例：

// 发送预定义消息
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",
  `I'm on the ${userPlan} plan and need help with advanced features`
);

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: 'Contact Support',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
  suggestions: ['What is GitBook?', 'How do I get started?']
});

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> } } （可选）

返回： string

示例：

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

client.createFrame(iframe)

创建一个用于与 iframe 通信的 frame 客户端。

参数：

• iframe: HTMLIFrameElement - iframe 元素

返回： GitBookFrameClient

示例：

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

Frame 客户端方法

frame.navigateToPage(path)

在文档选项卡中导航到特定页面。

参数：

• path: string - 页面路径

frame.navigateToAssistant()

切换到助手选项卡。

frame.postUserMessage(message)

向聊天发布消息。

参数：

• message: string - 要发布的消息

frame.clearChat()

清除聊天记录。

frame.configure(settings)

配置嵌入。参见 配置 部分 以获取可用选项。

frame.on(event, listener)

注册事件监听器。

参数：

• event: string - 事件名称

• listener: 函数 - 回调函数

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

示例：

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

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

React 组件 API

参见 React 集成指南 以获取组件 props 和 useGitBook hook API。