script 标签

了解如何使用单个 script 标签将 Docs Embed 小部件添加到任意网站或 Web 应用

将 GitBook Assistant 嵌入到你的网站或应用中的最简单集成方法，是在 HTML 中包含一个独立脚本。每个 GitBook 文档站点都会提供一个可直接使用的嵌入脚本，它会自动加载该组件并将其连接到你的文档。本页将告诉你如何操作。

不需要 SDK、构建步骤或框架集成。只需包含该脚本，组件就会出现在你的页面上。

开始使用

复制你的嵌入脚本 URL

在 GitBook 应用中进入你的文档站点，导航到设置标签页，然后进入 AI 与 MCP 并复制嵌入脚本 URL。

你也可以手动构建它：

https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js

将你的 YOUR_DOCS_DOMAIN 替换为你的真实文档站点域名。

将脚本添加到你的 HTML 中

在你的页面 HTML 中添加以下标签。将它放在 <head> 中，或者放在 </body>.

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>window.GitBook('show');</script>

如果你的文档需要身份验证

如果你的文档受身份验证保护，该脚本必须包含一个已签名的 JWT 令牌。

将它作为查询参数附加：

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js?jwt_token=YOUR_TOKEN"></script>

验证

重新加载你的页面。

该组件应出现在右下角。

可选地配置嵌入

你可以在显示组件之前自定义它。调用 configure 在脚本加载之后，并在调用 window.GitBook('show').

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('configure', {
    button: {
      label: '提问',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: '联系支持',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: '欢迎',
      subtitle: '我能如何帮助你？'
    },
    suggestions: [
      '什么是 GitBook？',
      '我该如何开始？'
    ]
  });

  window.GitBook('show');
</script>

使用此方法，你可以自定义：

按钮标签和图标
组件内可见的标签页
自定义操作按钮
问候标题和副标题
向用户显示的建议提示。

控制组件可见性

你可以通过 API 在运行时控制可见性和状态。

<script>
  // 使组件可见
  window.GitBook('show');

  // 从页面中移除组件
  window.GitBook('hide');

  // 打开组件面板
  window.GitBook('open');

  // 关闭组件面板
  window.GitBook('close');

  // 切换打开或关闭状态
  window.GitBook('toggle');
</script>

当你想将组件连接到自己的 UI 触发器时，这非常有用。

以编程方式导航和交互

你可以通过代码驱动该组件进行导航、切换标签页或发送消息。

<script>
  // 在组件内打开特定文档页面
  window.GitBook('navigateToPage', '/getting-started');

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

  // 向助手发送用户消息
  window.GitBook('postUserMessage', '我该如何开始？');

  // 清除当前聊天记录
  window.GitBook('clearChat');
</script>

此功能的典型用途包括：

从你的应用添加指向文档页面的深链接
预填一个问题
在不同流程之间重置对话

动态加载嵌入脚本

如果你只想有条件地加载该组件，或者需要在运行时附加身份验证令牌，请以编程方式注入该脚本。

<script>
  function loadGitBookEmbed() {
    var token = "" // 如果你的站点需要身份验证，请在此填入你的 JWT 令牌
    var script = document.createElement('script');
    script.src = 'https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js'
      + token ? '?jwt_token=' + encodeURIComponent(token) : '';
    script.async = true;
    script.onload = function () {
      window.GitBook('show');
    };
    document.head.appendChild(script);
  }

  loadGitBookEmbed();
</script>

当组件应仅在用户操作后或由功能标记控制时加载，请使用此模式

API 参考

初始化

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - 使用站点 URL 和可选的已认证访问初始化组件

小部件控制

GitBook('show') - 显示组件按钮
GitBook('hide') - 隐藏组件按钮
GitBook('open') - 打开组件窗口
GitBook('close') - 关闭组件窗口
GitBook('toggle') - 切换组件窗口

聊天

GitBook('postUserMessage', message: string) - 向聊天发送消息
GitBook('clearChat') - 清除聊天历史

配置

GitBook('configure', settings: {...}) - 配置组件设置（见下方“配置”部分）
GitBook('unload') - 将组件从页面中完全移除

配置选项

配置选项可通过 GitBook('configure', {...}):

`tabs`

覆盖显示哪些标签页。默认为你站点的配置。

输入: ('assistant' | 'docs')[]
选项:
- ['assistant', 'docs'] - 显示两个标签页
- ['assistant'] - 仅显示助手标签页
- ['docs'] - 仅显示文档标签页

`actions`

显示在侧边栏中、与标签页并列的自定义操作按钮。每个操作按钮在点击时都会触发回调。

注意：这之前名为 buttons。使用 actions 。

输入: Array<{ icon: string, label: string, onClick: () => void }>
属性:
- icon: 字符串 - 图标名称。任何 FontAwesome 图标都受支持
- label: 字符串 - 按钮标签文本
- onClick: () => void | Promise<void> - 点击时的回调函数

`greeting`

显示在 Assistant 标签页中的欢迎消息。

输入: { title: string, subtitle: string }

`suggestions`

显示在 Assistant 欢迎界面中的建议问题。

输入: string[]

`trademark`

在嵌入 UI 中显示或隐藏 GitBook 商标——包括 Docs Embed 页脚和 Assistant 品牌标识。

输入: boolean
默认: true
示例:

window.GitBook('configure', {
  trademark: false
});

`tools`

用于扩展 Assistant 的自定义 AI 工具。详情请参见创建自定义工具。

输入: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

`按钮`

配置用于启动嵌入的组件按钮（仅限独立脚本）。这使你可以自定义出现在页面右下角按钮的标签和图标。

输入: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
属性:
- label: 字符串 - 按钮上显示的文本
- icon: 'assistant' | 'sparkle' | 'help' | 'book' - 按钮上显示的图标
  - assistant - 助手图标
  - sparkle - 闪光图标
  - help - 帮助/问题图标
  - book - 书本图标

示例：

window.GitBook('configure', {
  button: {
    label: '提问',
    icon: 'assistant'
  }
});

注意： 此选项仅在使用独立 script 标签实现时可用。对于 React 或 Node.js 实现，你需要创建自己的按钮来触发嵌入。

`visitor` （已认证访问）

在使用以下方式初始化时传入 GitBook('init', options, frameOptions)。用于自适应内容并在已认证访问.

输入: { token?: string, unsignedClaims?: Record<string, unknown> }
属性:
- token: 字符串 （可选）- 已签名的 JWT 令牌
- unsignedClaims: Record<string, unknown> （可选）- 用于动态表达式的未签名声明

常见问题

脚本 URL 不正确 – 请确保你使用的是实际的文档 URL，而不是示例 docs.company.com.
在脚本加载前调用 GitBook – 将 API 调用包装在 script.onload 中，或将它们放在 script 标签之后。
无法访问需要认证的文档 – 如果你的文档需要登录，你必须提供 visitor.token 在初始化时。参见与已认证文档一起使用.
CORS 或 CSP 错误 – 确保你站点的内容安全策略允许从你的 GitBook 域加载脚本和 iframe。
组件不可见 – 检查页面中与其他元素的 z-index 冲突。该组件默认使用较高的 z-index。
忘记初始化 – 请确保调用 GitBook('init', { siteURL: '...' }) 之后再使用其他方法。

最后更新于1个月前

这有帮助吗？