React

使用预构建的 React 组件将 Docs Embed 添加到您的 React 应用中

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

步骤

安装包

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

npm install @gitbook/embed

有关完整的 API 参考和源代码，请参阅 @gitbook/embed GitHub 上的包.

导入 React 组件

导入 GitBookProvider 和 GitBookFrame 组件：

import {
  GitBookProvider,
  GitBookFrame,
} from "@gitbook/embed/react";

用 GitBookProvider 包装你的应用

在组件树的根部或需要嵌入的位置添加提供者：

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

添加 GitBookFrame 组件

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

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

自定义嵌入

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

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    tabs={['assistant', 'docs']}
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    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={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

使用 useGitBook 钩子控制嵌入

使用 useGitBook 钩子以编程方式与嵌入交互：

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('How do I get started?');
  };

  return <button onClick={handleNavigate}>Get Help</button>;
}

有条件地渲染嵌入

仅在需要时显示嵌入：

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

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>Get Help</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}

与 Next.js 或服务端渲染一起使用

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

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 }
);

属性与配置

GitBookProvider 属性：

属性

类型

必需

默认值

描述

siteURL

字符串

是

不适用

你的 GitBook 文档站点 URL（例如， https://docs.company.com).

children

ReactNode

是

不适用

在提供者内渲染的子组件。

GitBookFrame 属性：

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

属性

类型

必需

默认值

描述

className

字符串

否

null

要应用到 frame 容器的 CSS 类名。

style

对象

否

{}

要应用到 frame 容器的内联样式。

visitor

对象

否

{}

认证访问选项（见下文）。

useGitBook 钩子：

返回一个 GitBookClient 实例，具有以下方法：

getFrameURL(options?: { visitor?: {...} }) → 字符串 - 获取 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`

覆盖显示哪些选项卡。默认使用你站点的配置。

类型: ('assistant' | 'docs')[]

`actions`

在侧边栏与选项卡并列渲染的自定义操作按钮。每个操作按钮在点击时会触发回调。

注意: 之前该项命名为 buttons。使用 actions 代替。

类型: Array<{ icon: string, label: string, onClick: () => void }>

`greeting`

在 Assistant 选项卡中显示的欢迎信息。

类型: { title: string, subtitle: string }

`suggestions`

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

类型: 字符串数组

`tools`

用于扩展 Assistant 的自定义 AI 工具。详见创建自定义工具以获取详细信息。

类型: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

`visitor` （认证访问）

用于自适应内容和认证访问.

类型: { token?: string, unsignedClaims?: Record<string, unknown> }

常见错误

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

最后更新于2天前

这有帮助吗？

下午好

步骤

安装包