# 脚本标签将 Docs Embed 添加到您的网站或应用的最简单方式，是在 HTML 中包含一个独立脚本。每个 GitBook 文档站点都会提供一个可直接使用的嵌入脚本，它会自动加载小组件并将其连接到您的文档。本页面将告诉您如何完成这一操作。无需 SDK、构建步骤或框架集成。只需包含该脚本，小组件就会出现在您的页面上。 ## 开始使用 {% stepper %} {% step %} ### 复制您的嵌入脚本 URL 在 GitBook 应用中进入您的文档站点，导航到 **设置** 选项卡，然后到 **AI 与 MCP** 并复制嵌入脚本 URL。您也可以手动构建： ``` https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js ``` 将您的 `YOUR_DOCS_DOMAIN` 替换为您真实文档站点的域名。 {% endstep %} {% step %} ### 将脚本添加到您的 HTML 中在页面 HTML 中添加以下标签。把它放在 `` 中，或放在 ``. ```html 之前。 ``` {% endstep %} {% step %} ### 如果您的文档需要身份验证如果您的文档 [位于身份验证之后](https://gitbook-v2-lrp5kto0w-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/site-access/authenticated-access)，脚本必须包含已签名的 JWT 令牌。将其作为查询参数附加： ```html ``` {% endstep %} {% step %} ### 验证重新加载您的页面。小组件应显示在右下角。 {% endstep %} {% endstepper %} ### 可选：配置嵌入您可以在显示之前自定义小组件。加载脚本后、调用之前，执行 `configure` ，然后再调用 `window.GitBook('show')`. ```html 之前。 ``` 使用此方法，您可以自定义： * 按钮标签和图标 * 小组件内可见的选项卡 * 自定义操作按钮 * 问候标题和副标题 * 向用户显示的建议提示。搜索默认启用。如果您设置 `tabs`，请列出您想保留的每个选项卡。 ### 设置配色方案默认情况下，嵌入内容会遵循 iframe 的 CSS `color-scheme`。这样它就能自动继承您的应用主题或浏览器偏好。如果您想强制使用某种模式，请初始化嵌入并传入 `colorScheme` 到 `frameOptions`: ```html 之前。 ``` 当您需要帧级别选项时，请使用此模式，例如 `colorScheme` 或 `visitor`. ### 控制小组件可见性您可以通过 API 在运行时控制可见性和状态。 ```html ``` 当您想将小组件与自己的 UI 触发器连接起来时，这很有用。 ### 以编程方式导航和交互您可以从代码中驱动小组件进行导航、切换选项卡或发送消息。 ```html ``` 此功能的典型用途包括： * 从您的应用添加指向文档页面的深度链接 * 预填问题 * 在不同流程之间重置对话 ### 动态加载嵌入脚本如果您只想有条件地加载小组件，或需要在运行时附加身份验证令牌，请以编程方式注入脚本。 ```html ``` 当小组件应仅在用户操作或功能开关之后加载时，请使用此模式 ## API 参考 ### 初始化 * `GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` - 使用站点 URL 和可选的帧选项初始化小组件 ### 小组件控制 * `GitBook('show')` - 显示小组件按钮 * `GitBook('hide')` - 隐藏小组件按钮 * `GitBook('open')` - 打开小组件窗口 * `GitBook('close')` - 关闭小组件窗口 * `GitBook('toggle')` - 切换小组件窗口 ### 导航 * `GitBook('navigateToPage', path: string)` - 导航到文档选项卡中的特定页面 * `GitBook('navigateToAssistant')` - 导航到助手选项卡 ### 聊天 * `GitBook('postUserMessage', message: string)` - 向聊天发送消息 * `GitBook('clearChat')` - 清除聊天记录 ### 配置 * `GitBook('configure', settings: {...})` - 配置小组件设置（见下方“配置”部分） * `GitBook('unload')` - 从页面中完全移除小组件 ## 配置选项 ### `GitBook('configure')` 大多数配置选项可通过以下方式使用： `GitBook('configure', {...})`: #### `tabs` 覆盖显示哪些选项卡。搜索默认启用。如果您设置 `tabs`，则嵌入内容仅显示您列出的选项卡。 * **类型**: `('assistant' | 'search' | 'docs')[]` * **选项**: * `['assistant', 'search', 'docs']` - 显示所有选项卡 * `['search', 'docs']` - 仅显示搜索和文档 * `['docs']` - 仅显示文档选项卡 #### `actions` 在侧边栏中与选项卡并排渲染的自定义操作按钮。每个操作按钮在点击时都会触发一个回调。 **注意**：这之前名为 `buttons`。请改用 `actions` 。 * **类型**: `Array<{ icon: string, label: string, onClick: () => void }>` * **属性**: * `icon`: `string` - 图标名称。支持任何 [FontAwesome 图标](https://fontawesome.com/search) 。 * `label`: `string` - 按钮标签文本 * `onClick`: `() => void | Promise` - 点击时的回调函数 #### `greeting` 在助手选项卡中显示的欢迎消息。 * **类型**: `{ title: string, subtitle: string }` #### `suggestions` 在助手欢迎界面中显示的建议问题。 * **类型**: `string[]` #### `trademark` 在嵌入 UI 中显示或隐藏 GitBook 商标——包括 Docs Embed 页脚和 Assistant 品牌标识。 * **类型**: `boolean` * **默认值**: `true` * **示例**: ```javascript window.GitBook('configure', { trademark: false }); ``` #### `tools` 用于扩展助手的自定义 AI 工具。详见 [创建自定义工具](https://gitbook-v2-lrp5kto0w-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/docs-site/embedding/configuration/creating-custom-tools) 了解详情。 * **类型**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>` #### `button` 配置启动嵌入的按钮（仅适用于独立脚本）。这允许您自定义页面右下角出现的按钮的标签和图标。 * **类型**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **属性**: * `label`: `string` - 按钮上显示的文本 * `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - 按钮上显示的图标 * `assistant` - 助手图标 * `sparkle` - 闪光图标 * `help` - 帮助/问号图标 * `book` - 书本图标 **示例：** ```javascript window.GitBook('configure', { button: { label: '提问', icon: 'assistant' } }); ``` {% hint style="info" %} **注意：** 此选项仅在使用独立脚本标签实现时可用。对于 React 或 Node.js 实现，您需要创建自己的按钮来触发嵌入。 {% endhint %} ### `frameOptions` 某些选项是在帧上设置的，而不是作为配置。请在调用时传入它们 `frameOptions` 当调用 `GitBook('init', options, frameOptions)`. #### `colorScheme` 覆盖嵌入的配色方案。如果省略，嵌入将遵循 iframe 的 CSS `color-scheme`，从而继承父页面或浏览器偏好。 * **类型**: `'light' | 'dark'` * **示例**: ```javascript window.GitBook( 'init', { siteURL: 'https://docs.company.com' }, { colorScheme: 'dark' } ); ``` #### `visitor` （已认证访问）在使用以下方式初始化时传入 `GitBook('init', options, frameOptions)`。用于 [自适应内容](https://gitbook-v2-lrp5kto0w-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/site-access/adaptive-content) 和 [已认证访问](https://gitbook-v2-lrp5kto0w-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/site-access/authenticated-access). * **类型**: `{ token?: string, unsignedClaims?: Record }` * **属性**: * `token`: `string` （可选）- 已签名的 JWT 令牌 * `unsignedClaims`: `Record` （可选）- 用于动态表达式的未签名声明 ## 常见问题 * **脚本 URL 不正确** – 请确保使用的是您的真实文档 URL，而不是示例 `docs.company.com`. * **在脚本加载前调用 GitBook** – 将 API 调用包装在 `script.onload` 中，或将它们放在脚本标签之后。 * **无法访问已验证身份的文档** – 如果您的文档需要登录，您必须提供 `visitor.token` ，并在初始化时传入。参见 [与经过身份验证的文档一起使用](https://gitbook-v2-lrp5kto0w-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/docs-site/embedding/using-with-authenticated-docs). * **CORS 或 CSP 错误** – 确保您网站的内容安全策略允许从您的 GitBook 域加载脚本和 iframe。 * **小组件不可见** – 检查您页面上其他元素是否存在 z-index 冲突。默认情况下，小组件使用较高的 z-index。 * **忘记初始化** – 请确保在使用其他方法之前调用 `GitBook('init', { siteURL: '...' })` 。