API 参考

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

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

方法比较

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

直接导航到助理标签。

示例：

// 切换到助理标签
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', {
  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 通信。

参数：

• iframe: HTMLIFrameElement - 该 iframe 元素

返回： GitBookFrameClient

示例：

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

框架客户端方法

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 集成指南 了解组件属性和 useGitBook hook API。