# Node.js/NPM

如果你需要更多控制并希望在应用层进行操作，你可以从 npm 安装 GitBook embed 包。这种方式非常适合服务端渲染、构建时集成或自定义 iframe 管理。

## 步骤

{% stepper %}
{% step %}
**将包安装**

添加 `@gitbook/embed` 到你的项目中：

```bash
npm install @gitbook/embed
```

如需完整的 API 参考和源代码，请参阅 GitHub 上的 [`@gitbook/embed` 包](https://github.com/GitbookIO/gitbook/tree/main/packages/embed).
{% endstep %}

{% step %}
**导入包**

在你的应用代码中，导入 `createGitBook` 函数：

```javascript
import { createGitBook } from "@gitbook/embed";
```

或者使用 CommonJS：

```javascript
const { createGitBook } = require("@gitbook/embed");
```

{% endstep %}

{% step %}
**初始化 GitBook**

使用你的文档站点 URL 创建一个 GitBook 实例：

```javascript
const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});
```

{% endstep %}

{% step %}
**创建一个 iframe**

生成一个 iframe 元素，并将其源设置为嵌入 URL：

```javascript
const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token', // 可选：用于自适应内容或已认证访问
    unsignedClaims: { // 可选：用于动态表达式的自定义声明
      userId: '123',
      plan: 'premium'
    }
  }
});
iframe.id = "gitbook-embed-container";
iframe.style.border = "none";
iframe.style.width = "100%";
iframe.style.height = "600px";
```

{% endstep %}

{% step %}
**挂载框架**

创建一个 GitBook 框架实例并将其挂载到你的页面：

```javascript
const frame = gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);
```

{% endstep %}

{% step %}
**以编程方式控制嵌入**

使用框架实例与嵌入内容交互：

```javascript
// 导航到文档标签页中的特定页面
frame.navigateToPage("/getting-started");

// 切换到助手选项卡
frame.navigateToAssistant();

// 向聊天发送消息
frame.postUserMessage("How do I get started?");

// 清除聊天历史
frame.clearChat();
```

{% endstep %}

{% step %}
**配置嵌入**

使用自定义选项配置嵌入：

```javascript
frame.configure({
  trademark: false,
  tabs: ['assistant', 'search', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: '联系支持',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: '欢迎！', subtitle: '我能帮你什么？' },
  assistantName: '支持副驾',
  closeButton: true,
  suggestions: ['What is GitBook?', 'How do I get started?'],
  tools: [/* ... */]
});
```

{% endstep %}

{% step %}
**监听事件**

注册事件监听器以响应嵌入事件：

```javascript
frame.on('close', () => {
  console.log('Frame 已关闭');
});

// 完成后取消订阅
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigated to:', data.path);
});
```

{% endstep %}
{% endstepper %}

## API 参考

### 客户端工厂

* `createGitBook(options: { siteURL: string })` → `GitBookClient`
* `client.getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` → `string` - 获取带有可选框架选项的 iframe URL
* `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient` - 创建一个框架客户端与 iframe 通信

### Frame 客户端方法

* `frame.navigateToPage(path: string)` → `void` - 导航到文档标签页中的特定页面
* `frame.navigateToAssistant()` → `void` - 切换到助手标签页
* `frame.postUserMessage(message: string)` → `void` - 向聊天发送消息
* `frame.clearChat()` → `void` - 清除聊天历史
* `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void` - 配置嵌入
* `frame.on(event: string, listener: Function)` → `() => void` - 注册事件监听器（返回取消订阅函数）

## 配置选项

大多数自定义选项可通过以下方式使用： `frame.configure({...})`.

#### `tabs`

覆盖要显示的标签页。

搜索默认启用。如果你设置 `tabs`，嵌入内容将只显示你列出的标签页。

* **输入**: `('assistant' | 'search' | 'docs')[]`

#### `actions`

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

**注意**：这之前被命名为 `buttons`。使用 `actions` 。

* **输入**: `Array<{ icon: string, label: string, onClick: () => void }>`

#### `greeting`

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

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

#### `assistantName`

覆盖 UI 中显示的助手名称。

* **输入**: `string`
* **最大长度**: `32` 字符

#### `closeButton`

在助手内部显示关闭按钮。

* **输入**: `boolean`

#### `suggestions`

在助手欢迎界面显示的建议问题。

* **输入**: `string[]`

#### `trademark`

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

* **输入**: `boolean`
* **默认**: `true`

#### `tools`

用于扩展助手的自定义 AI 工具。详见 [创建自定义工具](https://gitbook-v2-5hpihs24d-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?: {...} }>`

### 框架 URL 选项

某些选项会传递给 `getFrameURL({...})`.

#### `colorScheme`

覆盖嵌入的颜色方案。

如果省略，嵌入将遵循 iframe 的 CSS `color-scheme`，这使其能够继承父页面或浏览器偏好设置。

* **输入**: `'light' | 'dark'`

### `visitor` （已认证访问）

传递给 `getFrameURL({ visitor: {...} })`。用于 [自适应内容](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/zhan-dian-fang-wen/adaptive-content) 并 [已认证访问](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/zhan-dian-fang-wen/authenticated-access).

* **输入**: `{ token?: string, unsignedClaims?: Record<string, unknown> }`

## 常见陷阱

* **忘记安装包** – 在导入之前运行 `npm install @gitbook/embed` 。
* **缺少 siteURL** – `siteURL` 选项是必需的，并且必须与你已发布的文档站点匹配。
* **iFrame 未渲染** – 确保父容器具有足够的宽度/高度以显示 iframe。
* **在初始化之前调用了框架方法** – 等待 `createFrame()` 完成后再调用框架方法。
* **未取消订阅事件** – 记得调用 `frame.on()` 返回的取消订阅函数，以防止内存泄漏。
* **使用旧版 API 方法** – 像 `open()`, `close()`, `toggle()`，以及 `destroy()` 这样的方式在 NPM 包中不可用。请改用框架客户端方法。