# React

对于 React 项目，GitBook 提供了预构建组件，使嵌入文档变得简单且符合惯用方式。这些组件会自动处理状态管理、上下文和生命周期。

## 步骤

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

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

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

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

{% step %}
**导入 React 组件**

导入 `GitBookProvider` 并 `GitBookFrame` components:

```jsx
导入 {
  GitBookProvider,
  GitBookFrame,
} from "@gitbook/embed/react";
```

{% endstep %}

{% step %}
**使用 GitBookProvider 包裹你的应用**

将 provider 添加到组件树的根部，或添加到你需要嵌入的地方：

```jsx
function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <YourAppContent />
    </GitBookProvider>
  );
}
```

{% endstep %}

{% step %}
**添加 GitBookFrame 组件**

将 frame 组件放在你希望嵌入内容出现的位置：

```jsx
function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <div className="app">
        <YourAppContent />
        <GitBookFrame
          visitor={{
            token: 'your-jwt-token', // 可选：用于自适应内容或已认证访问
            unsignedClaims: { userId: '123' } // 可选：用于动态表达式的自定义声明
          }}
        />
      </div>
    </GitBookProvider>
  );
}
```

{% endstep %}

{% step %}
**自定义嵌入**

将配置属性传递给 frame 组件：

```jsx
<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    tabs={['assistant', 'search', 'docs']}
    colorScheme="dark"
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    assistantName="Support Copilot"
    closeButton={true}
    suggestions={['GitBook 是什么？', '我该如何开始？']}
    actions={[
      {
        icon: 'circle-question',
        label: '联系支持',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>
```

如果你省略 `colorScheme`，嵌入内容会遵循 iframe 的 CSS `color-scheme`。这样它就能自动匹配你的应用主题。
{% endstep %}

{% step %}
**使用 useGitBook Hook 控制嵌入内容**

使用 `useGitBook` hook 来以编程方式与嵌入内容交互：

```jsx
import { useGitBook } from "@gitbook/embed/react";

function HelpButton() {
  const gitbook = useGitBook();
  const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
  
  const handleNavigate = () => {
    const iframe = document.createElement('iframe');
    iframe.src = frameURL;
    const frame = gitbook.createFrame(iframe);
    frame.navigateToPage('/getting-started');
    frame.navigateToAssistant();
    frame.postUserMessage('我该如何开始？');
  };

  return <button onClick={handleNavigate}>获取帮助</button>;
}
```

{% endstep %}

{% step %}
**条件性渲染嵌入内容**

仅在需要时显示嵌入内容：

```jsx
function App() {
  const [showEmbed, setShowEmbed] = useState(false);

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>获取帮助</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}
```

{% endstep %}

{% step %}
**与 Next.js 或服务端渲染一起使用**

动态导入这些组件以避免 SSR 问题：

```jsx
import dynamic from "next/dynamic";

const GitBookProvider = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookProvider),
  { ssr: false }
);

const GitBookFrame = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookFrame),
  { ssr: false }
);
```

{% endstep %}
{% endstepper %}

## 属性与配置

**GitBookProvider 属性：**

| 属性         | 输入          | 必填 | 默认  | 说明                                                   |
| ---------- | ----------- | -- | --- | ---------------------------------------------------- |
| `siteURL`  | `string`    | 是  | 不适用 | 你的 GitBook 文档站点 URL（例如， `https://docs.company.com`). |
| `children` | `ReactNode` | 是  | 不适用 | 要在 provider 内渲染的子组件。                                 |

**GitBookFrame 属性：**

所有配置选项都可以作为属性传递给 `<GitBookFrame>`。可用选项请参见下方的配置部分。

| 属性              | 输入                  | 必填 | 默认                     | 说明                    |
| --------------- | ------------------- | -- | ---------------------- | --------------------- |
| `className`     | `string`            | 否  | `null`                 | 应用于 frame 容器的 CSS 类名。 |
| `style`         | `object`            | 否  | `{}`                   | 应用于 frame 容器的内联样式。    |
| `colorScheme`   | `'light' \| 'dark'` | 否  | 继承自 CSS `color-scheme` | 覆盖嵌入的颜色方案。            |
| `assistantName` | `string`            | 否  | `null`                 | 覆盖 UI 中显示的助手名称。       |
| `closeButton`   | `boolean`           | 否  | `null`                 | 在助手内部显示关闭按钮。          |
| `visitor`       | `object`            | 否  | `{}`                   | 已认证访问选项（见下文）。         |

**useGitBook Hook：**

返回一个 `GitBookClient` 实例，包含以下方法：

* `getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` → `string` - 获取 iframe URL
* `createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient` - 创建 frame 客户端

frame 客户端提供：

* `navigateToPage(path: string)` → `void`
* `navigateToAssistant()` → `void`
* `postUserMessage(message: string)` → `void`
* `clearChat()` → `void`
* `configure(settings: {...})` → `void`
* `on(event: string, listener: Function)` → `() => void`

## 配置选项

配置选项可作为 `<GitBookFrame>`:

### `tabs`

覆盖要显示的标签页。

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

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

### `colorScheme`

覆盖嵌入的颜色方案。

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

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

### `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 工具。详见 [创建自定义工具](/docs/documentation/zh/docs-site/embedding/configuration/creating-custom-tools.md) 了解详情。

* **输入**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>`

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

的属性使用 [自适应内容](/docs/documentation/zh/zhan-dian-fang-wen/adaptive-content.md) 并 [已认证访问](/docs/documentation/zh/zhan-dian-fang-wen/authenticated-access.md).

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

## 常见陷阱

* **未使用 GitBookProvider 包裹** – `GitBookFrame` 需要一个父级 `GitBookProvider` 才能正常工作。
* **在未使用动态导入的情况下与 SSR 一起使用** – 该组件使用浏览器 API，必须在 Next.js 或其他 SSR 框架中通过动态导入。
* **siteURL 与已发布文档不匹配** – 请确保 `siteURL` 属性与你线上文档站点的 URL 完全一致。
* **在 provider 之外调用 useGitBook** – `useGitBook` hook 必须在一个组件内使用，而该组件必须是 `GitBookProvider`.
* **树中存在多个 provider** – 避免嵌套多个 `GitBookProvider` 实例，因为这可能会导致上下文冲突。
* **使用旧的组件名称** – 该组件现在是 `GitBookFrame`，而不是 `GitBookAssistantFrame`.


---

# Agent Instructions: 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:

```
GET https://gitbook.com/docs/documentation/zh/docs-site/embedding/implementation/react.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.