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 })→GitBookClientclient.getFrameURL(options?: { colorScheme?: 'light' | 'dark', visitor?: {...} })→stringclient.createFrame(iframe: HTMLIFrameElement)→GitBookFrameClient
框架客户端 :
frame.navigateToPage(path: string)→void(接受站点内的页面路径,绝对路径,或完整已公布的 URL;在任意空格/分区中解决页面)frame.navigateToAssistant()→voidframe.postUserMessage(message: string)→voidframe.clearChat()→voidframe.configure(settings: Partial<GitBookEmbeddableConfiguration>)→voidframe.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> } - 属性数字 :
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。 。 。 .