# @gitbook/embed 中文文档

规范地址：https://npmcn.com/package/%40gitbook/embed/

版本：0\.7\.0
npm 元数据更新时间：2026-11-12T10:47:17.233Z
中文译文更新时间：2026-11-16T10:31:11.875Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gitbook/embed
原文对照：https://npmcn.com/package/%40gitbook/embed/?lang=original
项目主页：https://github.com/GitbookIO/gitbook#readme
源码仓库：https://github.com/GitbookIO/gitbook

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：58.1 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \*
- 首次发布：2025-08-26T12:24:09.247Z
- 最新版本发布：2026-11-12T10:47:16.836Z
- 近 30 天下载量：219643（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 8 个）

## 中文简介

GitBook 可嵌入组件

## 安装

```sh
npm install @gitbook/embed
```

也可以使用：`pnpm add @gitbook/embed`、`yarn add @gitbook/embed`、`bun add @gitbook/embed`

## README

# GitBook Docs 嵌入( K)`@gitbook/embed`(中文(简体) )

在您的产品或网站上嵌入您的 GitBook 文件 .

嵌入式文档可包含三个标签:

-   **助理**编号: [GitBook 助理 翻译](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) - 一个AI驱动的聊天界面,帮助用户找到答案
-   **搜索**: 以搜索为重点的表面,以快速查找页面并询问范围问题
-   **文档**: 一个浏览器,用于浏览您的文档网站

嵌入基于您的站点配置自动设置 。 您可以通过自定义动作、工具、建议的问题来选择自定义和覆盖配置, [认证访问](https://gitbook.com/docs/publishing-documentation/authenticated-access)还有更多 见 [配置](https://npmcn.com/package/%40gitbook/embed/#readme-configuration) 用于所有可用选项的段落.

# 使用量

## 作为您文档网站的独立脚本

所有 GitBook 文档网站都包含一个脚本, 以方便您在网站上添加嵌入为部件的 Docs Embed .

剧本在 `https://docs.company.com/~gitbook/embed/script.js`。 。 。 .

您可以从您的 Docs 站点设置中找到嵌入的脚本, 或者复制以下并替换 `docs.company.com` 使用您的文档网站主机名.

```html
<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
```

脚本初始化了部件本身, 所以没有什么可以调用的 。 将嵌入于一色 方案,将其放入脚本 URL 上——它必须在部件制作前知道:

```html
<script src="https://docs.company.com/~gitbook/embed/script.js?theme=light"></script>
```

要验证访客,打电话 `init` 带着他们的纪念品 脚本 URL 中保留指使符: 是 可公开缓存,最后会出现在服务器日志中.

```html
<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
window.GitBook('init',
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
);
</script>
```

独立脚本提供全局性 `GitBook` 函数。 见 [API 参考](https://npmcn.com/package/%40gitbook/embed/#readme-api-reference) 所有可用方法的章节.

### 示例:配置部件

```javascript
GitBook('configure', {
    button: {
        label: 'Ask',
        icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
    },
    tabs: ['assistant', 'search', 'docs'],
    defaultPage: '/getting-started',
    actions: [
        {
            icon: 'circle-question',
            label: 'Contact Support',
            onClick: () => window.open('https://support.example.com', '_blank')
        }
    ],
    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
    assistantName: 'Support Assistant',
    suggestions: ['What is GitBook?', 'How do I get started?'],
    tools: [/* ... */],
    closeButton: true,
});
```

见 [配置](https://npmcn.com/package/%40gitbook/embed/#readme-configuration) 用于所有可用选项的段落.

## 作为国家预防机制的一揽子措施

安装软件包 : `npm install @gitbook/embed` 并导入到您的网络应用程序中 :

```tsx
import { createGitBook } from '@gitbook/embed';

const gitbook = createGitBook({
    siteURL: 'https://docs.company.com'
});

// Create an iframe and get its URL
const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL({
    colorScheme: 'dark', // Optional: force the embed to render in dark mode
    visitor: {
        token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
        unsignedClaims: { // Optional: custom claims for dynamic expressions
            userId: '123',
            plan: 'premium'
        }
    }
});

// Create a frame client to communicate with the iframe
const frame = gitbook.createFrame(iframe);

// Use the frame client methods
frame.navigateToPage('/getting-started'); // Navigate to a page in the docs tab
frame.navigateToAssistant(); // Switch to the assistant tab
frame.postUserMessage('How do I get started?');
frame.clearChat();

// Configure the embed (see Configuration section for all options)
frame.configure({
    tabs: ['assistant', 'search', 'docs'],
    defaultPage: '/getting-started',
    actions: [
        {
            icon: 'circle-question',
            label: 'Contact Support',
            onClick: () => window.open('https://support.example.com', '_blank')
        }
    ],
    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
    assistantName: 'Support Assistant',
    suggestions: ['What is GitBook?', 'How do I get started?'],
    tools: [/* ... */],
    closeButton: true
});

// Listen to events
frame.on('close', () => {
    console.log('Frame closed');
});
```

## 作为反应组件

在安装国家防范机制包后,您可以导入预建的 React 组件 :

```tsx
import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';

<GitBookProvider siteURL="https://docs.company.com">
    <GitBookFrame
        colorScheme="dark"
        visitor={{
            token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
            unsignedClaims: { userId: '123' } // Optional: custom claims for dynamic expressions
        }}
        tabs={['assistant', 'search', 'docs']}
        defaultPage="/getting-started"
        greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
        assistantName="Support Assistant"
        suggestions={['What is GitBook?', 'How do I get started?']}
        actions={[
            {
                icon: 'circle-question',
                label: 'Contact Support',
                onClick: () => window.open('https://support.example.com', '_blank')
            }
        ]}
        tools={[/* ... */]}
        closeButton
    />
</GitBookProvider>
```

你也可以使用这个 `useGitBook` 访问客户端的钩 :

```tsx
import { useGitBook } from '@gitbook/embed/react';

function MyComponent() {
    const gitbook = useGitBook();
    const frameURL = gitbook.getFrameURL({ colorScheme: 'dark', visitor: { token: '...' } });
    // ...
}
```

# API 参考

## 方法比较

| 方法 | 独立脚本 | 国家防范机制一揽子计划 | 反应组件 |
| --- | --- | --- | --- |
| **初始化** | `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)` | Via 帧客户端 |
| **导航到助手** | `GitBook('navigateToAssistant')` | `frame.navigateToAssistant()` | Via 帧客户端 |
| **邮件** | `GitBook('postUserMessage', message)` | `frame.postUserMessage(message)` | Via 帧客户端 |
| **清除聊天** | `GitBook('clearChat')` | `frame.clearChat()` | Via 帧客户端 |
| **配置** | `GitBook('configure', settings)` | `frame.configure(settings)` | 上标 `<GitBookFrame>` |
| **活动听众** | ❌ | `frame.on(event, listener)` | Via 帧客户端 |
| **卸载** | `GitBook('unload')` | ❌ | ❌ |

## 签署方法

### 独立脚本

-   `GitBook('init', options: { siteURL: string }, frameOptions?: { colorScheme?: 'light' | 'dark', visitor?: {...} })` - 初始化部件
-   `GitBook('show')` - 显示部件按钮
-   `GitBook('hide')` - 隐藏部件按钮
-   `GitBook('open')` - 打开部件窗口
-   `GitBook('close')` - 关闭部件窗口
-   `GitBook('toggle')` - 切换部件窗口
-   `GitBook('navigateToPage', path: string)` - 页面导航(接受站点内的页面路径、绝对路径或全部已公布的 URL;在任意空格/区段解决页面)
-   `GitBook('navigateToAssistant')` - 导航到助理标签
-   `GitBook('postUserMessage', message: string)` - 要聊天的邮寄信息
-   `GitBook('clearChat')` - 清谈历史
-   `GitBook('configure', settings: {...})` - 配置部件
-   `GitBook('unload')` - 卸载部件

### 国家防范机制一揽子计划

**客户工厂 :**

-   `createGitBook(options: { siteURL: string })` → `GitBookClient`
-   `client.getFrameURL(options?: { colorScheme?: 'light' | 'dark', visitor?: {...} })` → `string`
-   `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient`

**框架客户端 :**

-   `frame.navigateToPage(path: string)` → `void` (接受站点内的页面路径,绝对路径,或完整已公布的 URL;在任意空格/分区中解决页面)
-   `frame.navigateToAssistant()` → `void`
-   `frame.postUserMessage(message: string)` → `void`
-   `frame.clearChat()` → `void`
-   `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void`
-   `frame.on(event: string, listener: Function)` → `() => void` (未订阅)

### 反应组件

**组件 :**

-   `<GitBookProvider siteURL: string>` - 供应商部分
-   `<GitBookFrame {...props}>` - 框架组件(接受所有配置选项为道具)

**钩子:**

-   `useGitBook()` → `GitBookClient` (必须在 `<GitBookProvider>`(中文(简体) )

# 配置

各种使用方法的配置选项如下:

-   **独立的脚本**:通过 `GitBook('configure', {...})`
-   **国家防范机制一揽子计划**:通过 `frame.configure({...})`
-   **反应组件**: 通过道具打开 `<GitBookFrame>`

### `tabs`

可用于:独立脚本、国家防范机制软件包、反应组件

覆盖显示的标签 。 默认您的网站配置 .

-   **类型**数字 : `('assistant' | 'search' | 'docs')[]`

```javascript
tabs: ['assistant', 'search', 'docs']
```

### `defaultTab`

可用于:独立脚本、国家防范机制软件包、反应组件

嵌入式标签打开 。 没有它,嵌入层打开 `defaultPage` 如果设置了,则在助手(或当助手不可用时的docs)上另加. 标签必须是启用的 `tabs`。 。 。 .

-   **类型**数字 : `'assistant' | 'search' | 'docs'`

```javascript
tabs: ['assistant', 'search', 'docs'],
defaultTab: 'search'
```

`defaultTab` 财务报告和审定财务报表 `defaultPage` 当嵌入了第一个负载时适用:独立部件关闭并重新打开时保留其位置。 以后再移动,用 `navigateToPage` 或者说 `navigateToAssistant`。 。 。 .

### `defaultPage`

可用于:独立脚本、国家防范机制软件包、反应组件

文件标签打开的一页,取而代之的是您网站的主页。 接受与 `navigateToPage`:该页面在站点内的路径,绝对路径,或其已完全公布的URL. 除非我们.. `defaultTab` 否则,嵌入物将打开这个页面.

-   **类型**数字 : `string`

```javascript
defaultPage: '/getting-started/quickstart'
```

### `closeButton`

可用于:独立脚本、国家防范机制软件包、反应组件

显示关闭( E)`x`) 嵌入边栏的按钮.

-   **类型**数字 : `boolean`
-   **默认**数字 : `false`

```javascript
closeButton: true
```

行为:

-   点击时,嵌入式发送一个 `close` 事件到主页.
-   在独立的脚本中,此事件会自动处理并关闭部件 .
-   在自定义 iframe 集成( NPM 软件包) 中,您必须聆听 `close` 决定如何隐藏/压缩您的用户界面.
-   在 React 中,此功能在使用标准部件流时会自动工作. 如果构建自定义框架线, 处理 `close` 与国家预防机制一揽子计划相同.

国家防范机制一揽子计划的例子:

```typescript
const frame = gitbook.createFrame(iframe);

frame.configure({
    closeButton: true
});

const unsubscribe = frame.on('close', () => {
    // Hide your modal/drawer/container
    container.classList.add('hidden');
});
```

注释:

-   关闭按钮作为标签/动作在同一侧边栏区域提供.
-   如果你的UI隐藏了侧边栏或者没有将其制取出来,按钮就看不到了.

### `trademark`

可用于:独立脚本、国家防范机制软件包、反应组件

在嵌入处显示 GitBook 品牌 。 默认为真.

-   **类型**数字 : `boolean`
-   **默认**数字 : `true`

```javascript
trademark: true
```

### `actions`

可用于:独立脚本、国家防范机制软件包、反应组件

自定义侧边栏和标签旁的动作按钮 。 每个动作按钮点击时会触发回叫.

**说明**: 此道具先前命名为 `buttons`启用 `actions` 相反,它具有同样的功能.

-   **类型**数字 : `GitBookEmbeddableActionDefinition[]`
-   **属性**数字 :
    -   `icon`数字 : `string` - 图标名称。 任意 [字体帅气图标](https://fontawesome.com/search) 支持。 (例如, `'rocket'`, (中文(简体) ), `'comments'`, (中文(简体) ), `'user-circle'`, (...) (中文(简体) )
    -   `label`数字 : `string` - 按钮标签文本
    -   `onClick`数字 : `() => void | Promise<void>` - 点击时召回函数

```javascript
actions: [
    {
        icon: 'comments',
        label: 'Contact Support',
        onClick: () => window.open('https://support.example.com', '_blank')
    },
    {
        icon: 'rocket',
        label: 'Get started',
        onClick: () => {
            GitBook('navigateToPage', '/getting-started');
        }
    }
]
```

### `greeting`

可用于:独立脚本、国家防范机制软件包、反应组件

欢迎信件显示于 [助理](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) 选项卡.

-   **类型**数字 : `{ title: string, subtitle: string }`

```javascript
greeting: {
    title: 'Welcome!',
    subtitle: 'How can I help you today?'
}
```

### `assistantName`

可用于:独立脚本、国家防范机制软件包、反应组件

覆盖聊天头和助手出入口中显示的助手名(例如侧边栏标签和动作标签). 此名称将限于32个字符来防止文本外溢.

-   **类型**数字 : `string`

```javascript
assistantName: 'Support Assistant'
```

### `suggestions`

可用于:独立脚本、国家防范机制软件包、反应组件

建议的问题载于本文件附件一 [助理](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) 欢迎屏幕.

-   **类型**数字 : `string[]`

```javascript
suggestions: [
    'What is GitBook?',
    'How do I get started?',
    'What can you do?'
]
```

### `tools`

可用于:独立脚本、国家防范机制软件包、反应组件

自定义 AI 工具来扩展 [助理](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant)。工具允许助理执行功能并与自己的系统相集.

**说明**:除了定制工具外,助理将永远能够接触任何 [您定义的 MCP 服务器](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant#extend-gitbook-assistant-with-mcp-servers) 在您的网站的 AI 设置中.

-   **类型**数字 : `GitBookToolDefinition[]`
-   **属性**数字 :
    -   `name`数字 : `string` - 独特的工具标识符
    -   `description`数字 : `string` - 说明该工具的用途(大赦国际用来决定何时以及如何使用).
    -   `inputSchema`数字 : `object` - JSON 设计工具输入参数
    -   `execute`数字 : `(input: object) => Promise<{ output: any, summary: string }>` - 执行工具的 Async 函数.
        -   `output`:工具执行的结果,提供给AI继续合作. 未向用户显示 .
        -   `summary`:工具执行的视觉摘要,显示在用户聊天窗口.
    -   `confirmation`数字 : `{ icon?: string, label: string }` (可选) - 执行前显示的确认按钮,用于需要用户明示批准的行动.

```javascript
tools: [
    {
        name: 'get_user_info',
        description: 'Get information about the current user',
        inputSchema: {
            type: 'object',
            properties: {
                userId: { 
                    type: 'string', 
                    description: 'The user ID to look up' 
                }
            },
            required: ['userId']
        },
        execute: async (input) => {
            const user = await fetch(`/api/users/${input.userId}`).then(r => r.json());
            return {
                output: { name: user.name, plan: user.plan },
                summary: `Retrieved info for user ${user.name}`
            };
        }
    },
    {
        name: 'create_ticket',
        description: 'Create a support ticket',
        confirmation: {
            icon: 'circle-question',
            label: 'Create support ticket?'
        },
        inputSchema: {
            type: 'object',
            properties: {
                subject: { type: 'string' },
                description: { type: 'string' }
            },
            required: ['subject', 'description']
        },
        execute: async (input) => {
            const ticket = await fetch('/api/tickets', {
                method: 'POST',
                body: JSON.stringify(input)
            }).then(r => r.json());
            return {
                output: { ticketId: ticket.id },
                summary: `Created ticket #${ticket.id}`
            };
        }
    }
]
```

### `visitor` (认证访问)

可用于: 独立脚本(通过) `init`国家防范机制一揽子计划(通过 `getFrameURL()`),反应组件(作为道具)

[认证访问](https://gitbook.com/docs/publishing-documentation/authenticated-access) 选项在创建框架 URL 时通过。 用于 [适应性内容](https://gitbook.com/docs/publishing-documentation/adaptive-content) 财务报告和审定财务报表 [认证访问](https://gitbook.com/docs/publishing-documentation/authenticated-access)。 。 。 .

**说明**: 这不是一个配置选项,而是初始化帧或创建帧 URL时的参数.

**独立的脚本**: 传递作为第二个参数 `GitBook('init', options, frameOptions)` **国家防范机制一揽子计划**: 传到 `getFrameURL({ visitor: {...} })` **反应组件**: 通过为 `visitor` 打开道具 `<GitBookFrame>`

-   **类型**数字 : `{ token?: string, unsignedClaims?: Record<string, unknown> }`
-   **属性**数字 :
    -   `token`数字 : `string` (可选) - 签署 JWT 令牌 [适应性内容](https://gitbook.com/docs/publishing-documentation/adaptive-content) 或者说 [认证访问](https://gitbook.com/docs/publishing-documentation/authenticated-access)
    -   `unsignedClaims`数字 : `Record<string, unknown>` (可选) - 未签名的可用于动态表达式的债权通过 `visitor.claims.unsigned.<claim-name>`

```javascript
visitor: {
    token: 'your-jwt-token',
    unsignedClaims: {
        userId: '123',
        plan: 'premium',
        role: 'admin'
    }
}
```

### `colorScheme`

可用于: 独立脚本(通过) `init`国家防范机制一揽子计划(通过 `getFrameURL()`),反应组件(作为道具)

超越嵌入的颜色方案.

在省略时,独立部件遵循它嵌入的页面——它的 `color-scheme`,只有在网页上宣布支持两者时,才会回到访问者OS的偏好. 有了国家防范机制的软件包或反应组件,你拥有iframe,所以嵌入套件遵循了访客OS的偏好,除非你通过这个.

**说明**: 这不是一个配置选项,而是初始化帧或创建帧 URL时的参数.

**独立的脚本**数字 : `?theme=light` 脚本 URL **国家防范机制一揽子计划**: 传到 `getFrameURL({ colorScheme: 'dark' })` **反应组件**: 通过为 `colorScheme` 打开道具 `<GitBookFrame>`

-   **类型**数字 : `'light' | 'dark'`

```html
<script src="https://docs.company.com/~gitbook/embed/script.js?theme=light"></script>
```

以单一主题发布的网站 总是在那个主题,所以 `colorScheme` 没有任何影响 它们——部件跟随站点,使其铬和文件在站点内保持一致.

### `button`

仅提供独立的脚本

为独立的脚本配置部件按钮。 在使用国家防范机制软件包或反应组件时,无法使用这个选项,因为这些组件可以完全定制.

-   **类型**数字 : `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }`
-   **属性**数字 :
    -   `label`数字 : `string` - 按钮标签文本
    -   `icon`数字 : `'assistant' | 'sparkle' | 'help' | 'book'` - 图标显示在按钮上。 从4个预设中选择一个.

```javascript
button: {
    label: 'Ask',
    icon: 'assistant'
}
```

## 许可证

分发于 [Apache 许可证 2.0](https://npmcn.com/package/%40gitbook/embed/LICENSE)。 。 。 .

## 常见问题

### @gitbook/embed 是什么？

GitBook 可嵌入组件

### 如何安装 @gitbook/embed？

在项目目录运行 npm install @gitbook/embed，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gitbook/embed 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gitbook/embed 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gitbook/embed 可以商用吗？

@gitbook/embed 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @gitbook/embed 的下载量有多少？

根据 npm 官方下载统计，@gitbook/embed 在 2026/10/17 – 2026/11/15 这 30 天内被下载 219,643 次，日均约 7,321 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gitbook/embed 还在维护吗？

最新版本 0\.7\.0 发布于 2026/11/12（4 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 8 个；首次发布于 2025/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

