Typebot 前端嵌入库 typebot.io/js 完整指南Standard / Popup / Bubble 三种模式与变量预填充实战【免费下载链接】typebot.io Typebot is a powerful chatbot builder that you can self-host.项目地址: https://gitcode.com/GitHub_Trending/ty/typebot.ioTypebot 的官方前端嵌入库typebot.io/js是一套专为在任意网站上展示 Typebot 对话机器人而设计的浏览器端 SDK。它通过自定义元素Web Component与全局Typebot对象提供了Standard内嵌容器、Popup弹窗、Bubble聊天气泡三种开箱即用的挂载形态并内置变量预填充prefilled variables、自动展示延迟、主题定制与命令控制 API。阅读本文后你将掌握该库的 npm 与 CDN 两种安装方式、三种嵌入模式的完整配置项、窗口级命令调用方法以及如何利用 URL 查询参数和prefilledVariables实现个性化的会话初始化。一、库的定位与整体架构typebot.io/js是整个 Typebot 仓库中负责「前端渲染」的浏览器库源码位于 packages/embeds/js。它基于 SolidJS 与solid-element构建将所有组件封装为三个自定义元素自定义元素对应模式注册源码typebot-standard内嵌式容器register.tstypebot-bubble悬浮气泡register.tstypebot-popup居中弹窗register.ts从 web.ts 可以看到浏览器入口文件的职责非常清晰先调用registerWebComponents()注册自定义元素再通过parseTypebot()组装出包含initStandard、initPopup、initBubble以及全部命令方法的全局对象最后注入到window.Typebot见 window.ts。这意味着三种模式既可以声明式使用在 HTML 中直接写自定义元素标签也可以命令式使用调用Typebot.initXxx()动态创建所有控制指令打开、关闭、切换、重载等都通过window.postMessage与元素通信同一页面可承载多个 Typebot 实例并通过id参数精确定位目标实例。二、安装npm 与 CDN 两种方式1. 使用 npm 安装在支持打包器的前端项目中Vite、Next.js、Webpack 等推荐直接安装npm install typebot.io/js从 package.json 可以看出该包以 ESM 格式发布type: module并暴露两个入口默认入口.对应src/index.ts导出BotProps、BubbleProps、PopupProps等类型与全部命令函数适合在框架中按需引入子路径入口./web对应src/web.ts即上面提到的「注册组件 注入全局对象」的完整浏览器入口。包内还内置了完整的 TypeScript 类型声明dist/packages/embeds/js/src/index.d.ts因此在使用Typebot.initStandard(...)等 API 时能获得完善的类型提示。构建产物会通过 esbuild.config.cjs 在文件头部注入版本号 banner如// v0.10.9便于线上排查版本问题。2. 直接在 HTML 中通过 CDN 引入无需任何构建工具在页面中插入以下代码即可script typemodule import Typebot from https://cdn.jsdelivr.net/npm/typebot.io/js0/dist/web.js Typebot.initStandard({ typebot: my-typebot, }) /script typebot-standard stylewidth: 100%; height: 600px; /typebot-standard需要说明的是CDN 路径中的0表示跟随 0.x 大版本的最新发布正式环境建议锁定具体版本号如0.10.9以保证稳定性。initStandard在 window.ts 中的实现逻辑是优先通过id属性用document.getElementById查找已存在的typebot-standard元素找不到时则回退到document.querySelector(typebot-standard)然后把传入的配置通过Object.assign全部挂到该元素上若页面中不存在对应元素会直接抛出typebot-standard element not found.错误。因此自定义元素标签必须与初始化代码同时存在。三、Standard 模式内嵌到页面流中Standard 模式适合将机器人作为页面的一部分嵌入。你可以在 Typebot 编辑器的Share分享→ HTML Javascript面板中一键获取该代码。以宽度 100%、高度 600px 的容器为例script typemodule import Typebot from https://cdn.jsdelivr.net/npm/typebot.io/js0/dist/web.js; Typebot.initStandard({ typebot: my-typebot, }); /script typebot-standard stylewidth: 100%; height: 600px; /typebot-standard这段代码创建了一个宽度 100%跟随父容器宽度、高度 600px 的聊天容器。容器尺寸完全由typebot-standard标签上的style控制你可以在编辑器的分享面板中按需调整。从源码看Standard 模式有一个值得关注的优化在 Standard.tsx 中组件挂载后会创建一个IntersectionObserver来监听元素自身只有当容器进入视口时才真正加载并启动机器人launchBot()。这意味着位于页面底部的内嵌机器人不会拖慢首屏加载。此外该元素通过 Shadow DOM 隔离样式见hostElementCss宿主页面的全局 CSS 不会污染聊天界面。Standard 模式还支持templateSlug模板机器人、previewSettings/previewTheme预览模式下的设置与主题覆盖、isPreview预览标记、startFrom指定从某个组/块开始、sessionId/resultId会话与结果定位等高级属性完整定义见 Bot.tsx 中的BotProps。四、Popup 模式定时弹出的居中弹窗Popup 模式适合需要主动吸引访客注意力的场景。同样可以从Share → HTML Javascript面板获取script typemodule import Typebot from https://cdn.jsdelivr.net/npm/typebot.io/js0/dist/web.js; Typebot.initPopup({ typebot: my-typebot, apiHost: http://localhost:3001, autoShowDelay: 3000, }); /script上述代码会在页面加载3 秒后自动弹出机器人窗口。与 Standard 不同initPopupwindow.ts是动态创建typebot-popup元素并prepend到document.body因此无需预先在 HTML 中书写标签。Popup 支持的配置在 PopupParams 中定义配置项类型说明typebotstring要加载的 Typebot 标识slug 或 idapiHoststring聊天 API 的地址未指定时按 guessApiHost.ts 的规则自动推断优先取环境变量NEXT_PUBLIC_CHAT_API_URL其次NEXT_PUBLIC_VIEWER_URL兜底为云端地址autoShowDelaynumber页面加载后多少毫秒自动弹出默认不自动弹出theme.widthstring弹窗宽度theme.backgroundColorstring弹窗背景色theme.zIndexnumber弹窗层叠顺序用于压过页面其他浮层isOpen/defaultOpenboolean受控开关 / 挂载即打开关于自动弹出Popup.tsx 中还隐藏着一个贴心逻辑组件挂载时若设置了defaultOpen、检测到存储中有进行中的支付流程getPaymentInProgressInStorage()或存在上次打开的记录getBotOpenedStateFromStorage()会立即打开弹窗从而在刷新页面后恢复访客上次的会话状态。手动打开或关闭 Popup除了自动弹出你还可以在任何时机用命令控制弹窗Typebot.open();Typebot.close();Typebot.toggle();这三个命令同样适用于 Bubble 模式。命令的实现方式在 open.ts 中可以看得很清楚它构造一条{ isFromTypebot: true, command: open }消息并通过window.postMessage广播弹窗/气泡组件通过监听message事件接收并执行对应动作若传入id参数Typebot.open({ id: my-popup })则只有id匹配的元素会响应实现多实例精准控制。可以将命令绑定到任意按钮上例如button onclickTypebot.open()Contact us/button五、Bubble 模式悬浮气泡与预览消息Bubble 模式是最常用的客服/售前入口形态——页面右下角一个可点击的气泡按钮点击后展开聊天窗口并可选展示「预览消息」preview message来主动引导访客。示例代码如下script typemodule import Typebot from https://cdn.jsdelivr.net/npm/typebot.io/js0/dist/web.js; Typebot.initBubble({ typebot: my-typebot, previewMessage: { message: I have a question for you!, autoShowDelay: 5000, avatarUrl: https://avatars.githubusercontent.com/u/16015833?v4, }, theme: { button: { backgroundColor: #0042DA, iconColor: #FFFFFF }, previewMessage: { backgroundColor: #ffffff, textColor: black }, chatWindow: { backgroundColor: #ffffff }, }, }); /script该配置会在页面加载5 秒后于气泡上方浮现预览消息「I have a question for you!」点击预览消息或气泡即可打开聊天窗口。与 Popup 一样initBubble也是动态创建typebot-bubble元素并插入document.body。主题配置项详解Bubble 的主题定义在 bubble/types.ts包含三层结构button气泡按钮backgroundColor背景色、iconColor图标颜色、isHidden是否隐藏按钮配合嵌入消息触发、size尺寸medium、large或形如64px的自定义值、customIconSrc/customCloseIconSrc自定义展开/收起图标previewMessage预览消息backgroundColor背景色、textColor文字颜色、closeButtonBackgroundColor与closeButtonIconColor关闭按钮配色chatWindow聊天窗口backgroundColor背景色、maxWidth默认400px、maxHeight默认704px见 Bubble.tsx。此外还有两个布局级选项placement控制气泡在left左下还是right右下默认position控制定位方式为fixed固定悬浮默认还是static跟随文档流。还可以通过inlineStyle传入任意 CSS 键值对来微调容器样式。previewMessage本身支持message消息文本必填、avatarUrl头像地址、autoShowDelay延迟多少毫秒后自动展示三个字段。这些默认值与主题默认值的完整清单见 constants.ts。控制预览消息与聊天窗口预览消息可随时用命令控制Typebot.showPreviewMessage();Typebot.hidePreviewMessage();其中showPreviewMessage还支持传入自定义内容例如Typebot.showPreviewMessage({ message: 需要帮助吗, avatarUrl: /my-avatar.png })以动态替换当前预览消息对应ShowMessageCommandData见 commands/types.ts。聊天窗口本身同样由三个命令控制Typebot.open();Typebot.close();Typebot.toggle();同样可以直接绑定在按钮上button onclickTypebot.open()Contact us/button值得一提的是Bubble 组件对「打开过一次」的状态有记忆在 Bubble.tsx 的autoShowIfNeeded中若存储中存在已打开记录或进行中的支付流程会直接恢复打开状态autoShowDelay与previewMessage.autoShowDelay则各自驱动定时器实现自动展开与自动预览。六、完整命令 API 一览除了文档明示的open/close/toggle/showPreviewMessage/hidePreviewMessage从 features/commands/index.ts 可以看到库还导出了更多实用的运行时命令命令用途Typebot.open({ id? })打开 Popup / Bubble 聊天窗口Typebot.close({ id? })关闭聊天窗口Typebot.toggle({ id? })在打开/关闭之间切换Typebot.showPreviewMessage(message?)展示预览消息可传自定义内容Typebot.hidePreviewMessage({ id? })隐藏预览消息Typebot.setPrefilledVariables(variables, { id? })运行时追加预填充变量支持string \| number \| boolean值Typebot.setInputValue(value, { id? })程序化设置当前输入框的值Typebot.submitInput({ id? })提交当前输入Typebot.sendCommand(text, { id? })模拟用户发送一条消息Typebot.reload({ id? })重新加载机器人Typebot.reset({ id? })清除本地存储中的会话状态并重置Typebot.unmount({ id? })卸载组件会先播放关闭动画再移除所有命令都支持可选的id参数用于多实例定向。Bubble 组件处理这些命令的完整分支可以在 Bubble.tsx 的handlePostMessage中看到Standard 组件则额外支持setPrefilledVariables、reload、reset见 Standard.tsx。七、附加配置变量预填充Typebot 的变量Variables是贯穿整个机器人流程的占位符可以在气泡、条件块、结果表等任意位置引用详见仓库文档 apps/docs/editor/variables.mdx。嵌入时最常用的高级配置就是prefilledVariables——在会话开始前为机器人变量注入初始值例如Typebot.initStandard({ typebot: my-typebot, prefilledVariables: { Current URL: https://my-site/account, User name: John Doe, }, });运行后名为Current URL的变量会被填充为https://my-site/accountUser name变量被填充为John Doe。这样机器人第一轮对话就能直接引用这些值例如在开场白中显示访客姓名或用条件块跳过已预填的提问。注意变量名含空格时必须用引号包裹。URL 查询参数自动注入更省事的是如果你的站点 URL 本身带有查询参数变量会被自动注入到机器人中无需手动把参数搬运到嵌入配置里。例如访问https://my-site?User%20nameJohn%20Doe时User name变量会自动带上John Doe。这条规则的实现位于 Bot.tsx初始化时库会读取location.search的全部查询参数构造一个prefilledVariables对象再与代码中显式传入的prefilledVariables合并显式配置优先级更高最终随startChatQuery一起发给后端。这与 Typebot 编辑器文档中「变量可通过 URL 参数预填」的设计完全一致见 apps/docs/editor/variables.mdx 的 Prefilled variables 一节空格需编码为%20。因此在实际落地时你可以组合使用两种策略静态场景如营销活动落地页直接在prefilledVariables中写死utm_source、用户名等动态场景如用户已登录的站内页依靠 URL 查询参数自动注入页面只需保证参数名与机器人变量名一致。结合 commands/types.ts 中的setPrefilledVariables命令你甚至可以在会话进行中动态追加变量值进一步实现个性化旅程。八、进阶事件回调与状态持久化BotProps还定义了一组完整的事件回调见 Bot.tsx用于将机器人与宿主页面联动onInit机器人开始初始化时触发onNewInputBlock出现新的输入块时触发可借此做表单联动或分析埋点onAnswer用户每次回答时触发参数为{ message, blockId }onEnd流程结束时触发onNewLogs产生新的会话日志时触发onChatStatePersisted(isEnabled, { typebotId })会话状态是否被持久化与机器人设置中的「记住用户」相关持久化时会写入本地存储以便刷新恢复onScriptExecutionSuccess脚本块执行成功时触发。这些回调与rememberUser设置配合可以实现「访客刷新页面后继续上次对话」的完整体验相关存储读写逻辑集中在 utils/storage.ts。九、总结typebot.io/js以「自定义元素 全局命令对象」的双层 API 设计把三种嵌入形态统一在同一个库中Standard 适合内容页内嵌、Popup 适合定时触达、Bubble 适合常驻悬浮客服。结合prefilledVariables与 URL 参数自动注入机制可以轻松实现带上下文的高转化率对话体验命令系统open / close / toggle / setPrefilledVariables / reset 等则让宿主页面可以随时随地接管机器人的生命周期。上手建议先到 Typebot 编辑器的 Share 面板复制三段现成代码跑通三种模式再逐步加入theme主题定制、autoShowDelay自动展示与prefilledVariables变量预填最后通过id 命令 API 实现多实例、多入口的复杂站点集成。更完整的配置类型定义可查阅 packages/embeds/js/src/components/Bot.tsx、packages/embeds/js/src/features/bubble/types.ts 与 packages/embeds/js/src/features/popup/types.ts并可在 packages/embeds/js/src/features/commands 目录中逐一查看每个命令的实现细节。【免费下载链接】typebot.io Typebot is a powerful chatbot builder that you can self-host.项目地址: https://gitcode.com/GitHub_Trending/ty/typebot.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考