> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/fa-bu/embedding/implementation/script.md). # 脚本标签将 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 %} #### 如果你的文档需要身份验证如果你的文档 [受身份验证保护](/docs/documentation/zh/fa-bu/site-audience/authenticated-access.md)，脚本必须包含一个签名的 JWT 令牌。将其作为查询参数附加： ```html ``` {% endstep %} {% step %} #### 验证重新加载你的页面。小部件应出现在右下角。 {% endstep %} {% endstepper %} ### 可选地配置嵌入你可以在显示前自定义小部件。调用 `configure` ，在加载脚本之后、调用 `window.GitBook('show')`. ```html ``` 使用此方法，你可以自定义： * 按钮标签和图标 * 小部件内可见的选项卡 * 自定义操作按钮 * 问候语标题和副标题 * UI 中显示的助手名称 * 助手内的关闭按钮 * 向用户显示的建议提示。搜索默认启用。如果你设置 `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 和可选的 frame 选项初始化小部件 ### 小组件控制 * `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 }>` * **属性**: * `图标`: `string` - 图标名称。任何 [FontAwesome 图标](https://fontawesome.com/search) 都受支持 * `label`: `string` - 按钮标签文本 * `onClick`: `() => void | Promise` - 点击时的回调函数 #### `greeting` 显示在 Assistant 选项卡中的欢迎消息。 * **类型**: `{ title: string, subtitle: string }` #### `assistantName` 覆盖 UI 中显示的 assistant 名称。 * **类型**: `string` * **最大长度**: `32` 字符 * **示例**: ```javascript window.GitBook('configure', { assistantName: 'Support Copilot' }); ``` #### `closeButton` 在 Assistant 内部显示一个关闭按钮。 * **类型**: `boolean` * **示例**: ```javascript window.GitBook('configure', { closeButton: true }); ``` #### `suggestions` 显示在 Assistant 欢迎屏幕中的建议问题。 * **类型**: `string[]` #### `trademark` 在嵌入 UI 中显示或隐藏 GitBook 商标——包括 Docs Embed 页脚和 Assistant 品牌标识。 * **类型**: `boolean` * **默认**: `true` * **示例**: ```javascript window.GitBook('configure', { trademark: false }); ``` #### `tools` 用于扩展 Assistant 的自定义 AI 工具。详情请参见 [创建自定义工具](/docs/documentation/zh/fa-bu/embedding/configuration/creating-custom-tools.md) 。 * **类型**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>` #### `按钮` 配置启动嵌入的小部件按钮（仅限独立脚本）。这允许你自定义出现在页面右下角按钮的标签和图标。 * **类型**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **属性**: * `label`: `string` - 按钮上显示的文本 * `图标`: `'assistant' | 'sparkle' | 'help' | 'book'` - 按钮上显示的图标 * `assistant` - 助手图标 * `sparkle` - 闪光图标 * `help` - 帮助/问号图标 * `book` - 书本图标 **示例：** ```javascript window.GitBook('configure', { button: { label: 'Ask', icon: 'assistant' } }); ``` {% hint style="info" %} **注意：** 此选项仅在使用独立脚本标签实现时可用。对于 React 或 Node.js 实现，你需要创建自己的按钮来触发嵌入。 {% endhint %} ### `frameOptions` 某些选项是在 frame 上设置的，而不是作为配置。调用时将它们传入 `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)`。用于 [自适应内容](/docs/documentation/zh/fa-bu/adaptive-content.md) 并 [经过身份验证的访问](/docs/documentation/zh/fa-bu/site-audience/authenticated-access.md). * **类型**: `{ token?: string, unsignedClaims?: Record }` * **属性**: * `token`: `string` （可选）- 签名的 JWT 令牌 * `unsignedClaims`: `Record` （可选）- 用于动态表达式的未签名声明 ## 常见问题 * **脚本 URL 不正确** – 确保你使用的是实际的文档 URL，而不是示例 `docs.company.com`. * **在脚本加载前调用 GitBook** – 将 API 调用包装在 `script.onload` 中，或者将它们放在脚本标签之后。 * **受身份验证保护的文档无法访问** – 如果你的文档需要登录，你必须提供 `visitor.token` 在初始化时。请参阅 [与受身份验证保护的文档一起使用](/docs/documentation/zh/fa-bu/embedding/using-with-authenticated-docs.md). * **CORS 或 CSP 错误** – 确保你网站的内容安全策略允许从你的 GitBook 域加载脚本和 iframe。 * **小部件不可见** – 检查你页面上其他元素与 z-index 的冲突。该小部件默认使用较高的 z-index。 * **忘记初始化** – 确保调用 `GitBook('init', { siteURL: '...' })` 在使用其他方法之前。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/zh/fa-bu/embedding/implementation/script.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.