@gitbook/embed

中文文档
0.7.0发布于 2026/11/12Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 22万

GitBook 可嵌入组件

中文使用文档
文档目录23 节
  1. 作为您文档网站的独立脚本
  2. 示例:配置部件
  3. 作为国家预防机制的一揽子措施
  4. 作为反应组件
  5. 方法比较
  6. 签署方法
  7. 独立脚本
  8. 国家防范机制一揽子计划
  9. 反应组件
  10. tabs
  11. defaultTab
  12. defaultPage
  13. closeButton
  14. trademark
  15. actions
  16. greeting
  17. assistantName
  18. suggestions
  19. tools
  20. visitor (认证访问)
  21. colorScheme
  22. button
  23. 许可证

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

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

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

  • 助理编号: GitBook 助理 翻译 - 一个AI驱动的聊天界面,帮助用户找到答案
  • 搜索: 以搜索为重点的表面,以快速查找页面并询问范围问题
  • 文档: 一个浏览器,用于浏览您的文档网站

嵌入基于您的站点配置自动设置 。 您可以通过自定义动作、工具、建议的问题来选择自定义和覆盖配置, 认证访问还有更多 见 配置 用于所有可用选项的段落.

使用量

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

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

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

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

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

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

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

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

<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 参考 所有可用方法的章节.

示例:配置部件

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

见 配置 用于所有可用选项的段落.

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

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

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 组件 :

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 访问客户端的钩 :

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')[]
tabs: ['assistant', 'search', 'docs']

defaultTab

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

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

  • 类型数字 : 'assistant' | 'search' | 'docs'
tabs: ['assistant', 'search', 'docs'],
defaultTab: 'search'

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

defaultPage

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

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

  • 类型数字 : string
defaultPage: '/getting-started/quickstart'

closeButton

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

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

  • 类型数字 : boolean
  • 默认数字 : false
closeButton: true

行为:

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

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

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
trademark: true

actions

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

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

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

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

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

欢迎信件显示于 助理 选项卡.

  • 类型数字 : { title: string, subtitle: string }
greeting: {
    title: 'Welcome!',
    subtitle: 'How can I help you today?'
}

assistantName

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

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

  • 类型数字 : string
assistantName: 'Support Assistant'

suggestions

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

建议的问题载于本文件附件一 助理 欢迎屏幕.

  • 类型数字 : string[]
suggestions: [
    'What is GitBook?',
    'How do I get started?',
    'What can you do?'
]

tools

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

自定义 AI 工具来扩展 助理。工具允许助理执行功能并与自己的系统相集.

说明:除了定制工具外,助理将永远能够接触任何 您定义的 MCP 服务器 在您的网站的 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 } (可选) - 执行前显示的确认按钮,用于需要用户明示批准的行动.
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()),反应组件(作为道具)

认证访问 选项在创建框架 URL 时通过。 用于 适应性内容 财务报告和审定财务报表 认证访问。 。 。 .

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

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

  • 类型数字 : { token?: string, unsignedClaims?: Record<string, unknown> }
  • 属性数字 :
    • token数字 : string (可选) - 签署 JWT 令牌 适应性内容 或者说 认证访问
    • unsignedClaims数字 : Record<string, unknown> (可选) - 未签名的可用于动态表达式的债权通过 visitor.claims.unsigned.<claim-name>
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'
<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个预设中选择一个.
button: {
    label: 'Ask',
    icon: 'assistant'
}

许可证

分发于 Apache 许可证 2.0。 。 。 .

版本与发布记录

@gitbook/embed 共发布 13 个版本,首次发布于 2025/08/26;过去 12 个月发布了 8 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.7.0latest2026/11/124 天前
0.6.02026/10/2819 天前
0.5.12026/05/195 个月前
0.4.02026/03/118 个月前
0.3.02026/03/058 个月前
0.2.22026/02/258 个月前

关于 @gitbook/embed 的常见问题

@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 和提交记录判断。