# API 参考

Docs Embed 根据你的集成方式提供不同的 API。本参考文档涵盖所有集成方式中可用的全部方法。

## 方法对比

| 方法               | 独立脚本                                                         | NPM 包                            | React 组件                            |
| ---------------- | ------------------------------------------------------------ | -------------------------------- | ----------------------------------- |
| **初始化**          | `GitBook('init', options, frameOptions)`                     | `createGitBook(options)`         | `<GitBookProvider siteURL="...">`   |
| **获取 frame URL** | ❌（由内部处理）                                                     | `client.getFrameURL(options)`    | `useGitBook().getFrameURL(options)` |
| **创建 frame 客户端** | ❌（由内部处理）                                                     | `client.createFrame(iframe)`     | `useGitBook().createFrame(iframe)`  |
| **显示/隐藏小部件**     | `GitBook('show')` / `GitBook('hide')`                        | ❌                                | ❌                                   |
| **打开/关闭窗口**      | `GitBook('open')` / `GitBook('close')` / `GitBook('toggle')` | ❌                                | ❌                                   |
| **导航到页面**        | `GitBook('navigateToPage', path)`                            | `frame.navigateToPage(path)`     | 通过 frame 客户端                        |
| **导航到助手**        | `GitBook('navigateToAssistant')`                             | `frame.navigateToAssistant()`    | 通过 frame 客户端                        |
| **发送消息**         | `GitBook('postUserMessage', message)`                        | `frame.postUserMessage(message)` | 通过 frame 客户端                        |
| **清除聊天**         | `GitBook('clearChat')`                                       | `frame.clearChat()`              | 通过 frame 客户端                        |
| **配置**           | `GitBook('configure', settings)`                             | `frame.configure(settings)`      | 属性在 `<GitBookFrame>`                |
| **事件监听器**        | ❌                                                            | `frame.on(event, listener)`      | 通过 frame 客户端                        |
| **卸载**           | `GitBook('unload')`                                          | ❌                                | ❌                                   |

## 独立脚本 API

### 初始化

#### `GitBook('init', options, frameOptions)`

使用站点 URL 和可选的已认证访问来初始化小部件。

**参数：**

* `options`: `{ siteURL: string }` - 你的 GitBook 文档站点 URL
* `frameOptions`: `{ visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } }` （可选）- 已认证访问选项

**示例：**

```javascript
window.GitBook('init', 
  { siteURL: 'https://docs.company.com' },
  { visitor: { token: 'your-jwt-token' } }
);
```

### 小部件控制

#### 显示小部件

如果 GitBook 小部件已被隐藏，则将其显示出来。

**示例：**

```js
window.GitBook("show");
```

#### 隐藏小部件

隐藏 GitBook 小部件，但不卸载它。

**示例：**

```js
window.GitBook("hide");
```

#### 打开窗口

打开 Docs Embed 窗口。

**示例：**

```js
window.GitBook("open");
```

#### 关闭窗口

关闭 Docs Embed 窗口。

**示例：**

```js
window.GitBook("close");
```

#### 切换窗口

切换 Docs Embed 窗口的打开或关闭状态。

**示例：**

```js
window.GitBook("toggle");
```

#### 卸载小部件

从你的网站中完全移除 GitBook 小部件。

**示例：**

```js
window.GitBook("unload");
```

### 导航

#### `GitBook('navigateToPage', path)`

根据路径导航到 GitBook 文档中的特定页面。

**参数：**

* `path` （字符串）：你要导航到的页面路径

**示例：**

```javascript
// 导航到入门指南
window.GitBook("navigateToPage", "/getting-started");

// 导航到特定的 API 文档页面
window.GitBook("navigateToPage", "/api/authentication");

// 导航到 FAQ 部分
window.GitBook("navigateToPage", "/faq/billing");
```

#### `GitBook('navigateToAssistant')`

直接导航到助手标签页。

**示例：**

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

// 你可以在响应按钮点击时使用它
document.getElementById("help-button").addEventListener("click", () => {
  window.GitBook("navigateToAssistant");
});
```

### 聊天

#### `GitBook('postUserMessage', message)`

像用户输入的一样向聊天中发送一条消息。

**参数：**

* `message` （字符串）：要发送到聊天中的消息

**示例：**

```javascript
// 发送预设消息
window.GitBook("postUserMessage", "How do I reset my password?");

// 根据用户操作发送消息
function askAboutBilling() {
  window.GitBook("postUserMessage", "I have questions about my billing");
}

// 发送带有上下文的消息
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `我正在使用 ${userPlan} 套餐，需要高级功能方面的帮助`
);
```

#### `GitBook('clearChat')`

清除当前聊天会话中的所有消息。

**示例：**

```javascript
// 清除聊天
window.GitBook("clearChat");

// 清除聊天并开始新的对话
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "Hello, I need help with a new issue");
}

// 在切换上下文时清除聊天
document.getElementById("new-topic").addEventListener("click", () => {
  window.GitBook("clearChat");
  window.GitBook("navigateToAssistant");
});
```

### 配置

#### `GitBook('configure', settings)`

使用自定义选项配置嵌入。请参见 [配置部分](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/publishing-documentation/implementation/script#configuration-options) 以了解可用选项。

**示例：**

```javascript
window.GitBook('configure', {
  trademark: false,
  tabs: ['assistant', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: '联系支持',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: '欢迎！', subtitle: '我能为你做什么？' },
  suggestions: ['什么是 GitBook？', '我该如何开始？']
});
```

## NPM 包 API

### 客户端工厂

#### `createGitBook(options)`

创建一个 GitBook 客户端实例。

**参数：**

* `options`: `{ siteURL: string }` - 你的 GitBook 文档站点 URL

**返回：** `GitBookClient`

**示例：**

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

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

#### `client.getFrameURL(options)`

获取带有可选已认证访问的 iframe URL。

**参数：**

* `options`: `{ visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } }` （可选）

**返回：** `字符串`

**示例：**

```javascript
const iframeURL = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token',
    unsignedClaims: { userId: '123', plan: 'premium' }
  }
});
```

#### `client.createFrame(iframe)`

创建一个 frame 客户端以与 iframe 通信。

**参数：**

* `iframe`: `HTMLIFrameElement` - iframe 元素

**返回：** `GitBookFrameClient`

**示例：**

```javascript
const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL();
const frame = gitbook.createFrame(iframe);
```

### Frame 客户端方法

#### `frame.navigateToPage(path)`

导航到 docs 标签页中的特定页面。

**参数：**

* `path`: `字符串` - 页面路径

#### `frame.navigateToAssistant()`

切换到助手标签页。

#### `frame.postUserMessage(message)`

向聊天中发送一条消息。

**参数：**

* `message`: `字符串` - 要发送的消息

#### `frame.clearChat()`

清除聊天历史。

#### `frame.configure(settings)`

配置嵌入。请参见 [配置部分](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/publishing-documentation/implementation/nodejs#configuration-options) 以了解可用选项。

#### `frame.on(event, listener)`

注册事件监听器。

**参数：**

* `event`: `字符串` - 事件名称
* `listener`: `函数` - 回调函数

**返回：** `() => void` - 取消订阅函数

**示例：**

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

// 稍后取消订阅
unsubscribe();
```

## React 组件 API

请参见 [React 集成指南](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/publishing-documentation/embedding/implementation/react) 了解组件属性以及 `useGitBook` hook API。