ToolJet 应用预览与分享部署实战:从发布版本、公开链接到 iframe 嵌入

原创2026-09-12 23:29:241,857 阅读
文章标签:低代码前端后端企业应用

ToolJet 应用预览与分享部署实战:从发布版本、公开链接到 iframe 嵌入

导读

在 ToolJet 中构建完内部工具或业务应用后,把应用交付给团队与外部用户使用是最后、也是最关键的一步。本文将围绕 ToolJet 3.0.0-LTS 文档中的《Preview and Sharing Apps》主题,系统讲解三大实战能力:在编辑器中一键预览当前版本应用、通过自定义 slug 生成公开分享链接,以及使用 iframe 将应用嵌入第三方站点。文章不仅完整还原官方操作步骤,还会结合仓库中的前端组件与后端服务源码,说明每个按钮背后的 API 调用与访问控制逻辑,帮助你从"会用"进阶到"理解原理"。

预览(Preview):开发中的快速验收

ToolJet 编辑器右上角提供 Preview 入口,点击后会在新标签页打开当前正在编辑的版本。官方文档明确指出,这一功能的价值在于"立即以生产形态检查应用"——你无需先发布版本,就能模拟真实用户访问应用时的渲染效果、交互逻辑与页面布局。

从源码看,预览链接的构造逻辑位于 RightTopHeaderButtons.jsx:

const previewQuery = queryString.stringify({
  version: selectedVersion?.display_name || selectedVersion?.displayName || selectedVersion?.name,
  ...(featureAccess?.multiEnvironment ? { env: selectedEnvironment?.name } : {}),
});
setAppPreviewLink(
  editingVersion
    ? `/applications/${slug || appId}/${currentPageHandle}${!isEmpty(previewQuery) ? `?${previewQuery}` : ''}`
    : ''
);

这段实现揭示了预览的底层机制:

  • 基于路由参数而非独立页面:预览链接复用 /applications/:slug/:page 的应用查看路由,通过 URL 上的 version 查询参数指定要查看的版本,在多环境版本(multi-environment)开启时还会附加 env 参数指定环境;
  • slug 与 appId 互为回退:URL 优先使用应用 slug(如 customer-support-desk),不存在时才回退到内部 appId,这保证了应用更名或 slug 变更后预览依然可用;
  • 编辑态才生成预览:editingVersion 为空时预览链接为空字符串,说明"预览"只对正在编辑的草稿有意义。

预览页的头部组件 PreviewHeader.jsx 进一步说明了预览态的判定规则:它通过检查 URL 中是否携带 env 或 version 查询参数来识别预览模式,并且当应用处于公开访问(未登录)状态时不渲染预览头部,避免把编辑器专属控件暴露给匿名访客。

提示:预览使用的仍是"当前打开的版本",因此适合开发中的快速验收;正式对外分享前,请先完成版本发布(Release)。

分享应用(Sharing an app):三步生成公开链接

当某个版本已经发布(released)后,就可以通过分享功能把它交付给外部用户。官方文档给出的操作流程如下:

  1. 点击编辑器右上角的 Share 按钮(图标为分享箭头);
  2. 在弹出的对话框中,打开 Make the application public 开关,将应用设为公开可分享;
  3. 为应用创建自定义 URL(customised URL),点击 copy 复制链接;
  4. 可选:使用**嵌入链接(Embeddable link)**将应用嵌入自己的网站。

Share 对话框与源码对应

Share 按钮和整个分享对话框由 ManageAppUsers.jsx 组件实现。它被挂在编辑器右上角工具栏(见 RightTopHeaderButtons.jsx 中的 PreviewAndShareIcons),并通过 data-cy="editor-app-share-button" 暴露给自动化测试。

对话框内三个核心控件的测试锚点(data-cy)与功能一一对应:

界面元素 data-cy 作用
公开开关 make-application-public-toggle 切换应用公开/私有状态
可分享链接前缀 app-link 显示 ${host}/applications/ 前缀
slug 输入框 app-name-slug-input 自定义 URL 中友好 slug
复制链接按钮 copy-app-link-button 复制完整分享链接
嵌入链接 iframe-link 显示 iframe 嵌入代码

底层 API 调用链

前端分享功能最终落到两个服务方法(apps.service.js):

切换公开可见性 —— setVisibility(appId, visibility):

function setVisibility(appId, visibility) {
  const body = { app: { is_public: visibility } };
  const branchId = getActiveBranchId();
  if (branchId) body.app.branch_id = branchId;
  // PUT /api/apps/:appId/public
}

修改自定义 slug —— setSlug(appId, slug):

function setSlug(appId, slug) {
  const body = { app: { slug: slug } };
  const branchId = getActiveBranchId();
  if (branchId) body.app.branch_id = branchId;
  // PUT /api/apps/:appId
}

两点值得注意:

  • is_public 存储在应用实体上:PUT /apps/:id/public 请求体中的 is_public 字段对应服务端 apps 表/App 实体上的公开标志,后端的访问守卫通过它判断匿名访问是否被允许(详见下文);
  • Git 多分支场景:两个方法都会附加当前 branch_id,意味着公开状态与 slug 是分支级配置。组件源码中的 isShareLocked 逻辑表明:在多分支(multi-branching)开启时,默认/主分支上的分享配置被锁定,需要切换到功能分支才能修改(Tooltip 提示 "Master branch is locked. Switch branch to make the application public.")。

slug 校验与实时反馈

slug 输入框带 500ms 防抖(debounce),输入时会实时调用 validateName 校验,规则在 UI 上有明确提示:slug 由小写字母、数字和连字符组成,长度上限 50 字符(maxLength={50})。校验通过后调用 setSlug 更新应用,成功后界面显示 "Slug accepted!",失败则显示错误信息,同时组件会调用 replaceEditorURL 同步更新当前编辑器地址栏。

自定义 URL 与公开访问的权限模型

链接的组成

分享链接由 getHostURL() + '/applications/' + (slug || appId) 拼接而成(见 ManageAppUsers.jsx):

https://<你的 ToolJet 域名>/applications/<slug>
  • 未设置 slug 时回退使用应用 ID,但显然自定义 slug 更利于记忆与传播;
  • slug 修改后分享链接随之变化,旧链接将失效。

后端如何放行公开访问

当匿名用户访问公开应用时,服务端会经过访问守卫校验。核心逻辑在 validate-public-app.guard.ts:

const app = request.tj_app;
if (!app?.isPublic) {
  return true; // 非公开应用,交由后续鉴权流程处理
}
// Cloud 版本下对 Basic/Trial/Starter 计划限制公开应用
if (getTooljetEdition() === TOOLJET_EDITIONS.Cloud) {
  const licenseTerms = await this.licenseTermsService.getLicenseTerms(
    [LICENSE_FIELD.STATUS, LICENSE_FIELD.PLAN],
    app.organizationId
  );
  if (licenseType === LICENSE_TYPE.BASIC || licenseType === LICENSE_TYPE.TRIAL || planType === 'starter') {
    throw new ForbiddenException('public-app-plan-restricted');
  }
}

从源码可以得出三个关键事实:

  1. isPublic(对应 is_public)是应用级字段,公开与否由应用实体上的标志位决定;
  2. 公开分享面向的是已发布版本:配合 app-auth.guard.ts、valid-app.guard.ts 等其他守卫,未发布版本不会对外暴露;
  3. 公开应用存在计划限制:ToolJet Cloud 的 Basic/Trial/Starter 计划会拒绝公开应用访问(返回 public-app-plan-restricted),自托管社区版不受此限制。

嵌入应用:一行 iframe 接入自有站点

分享对话框在应用为公开状态(或实例开启了 ENABLE_PRIVATE_APP_EMBED 环境变量)时,会额外展示 Embedded app link(嵌入链接)。生成的 iframe 代码由 ManageAppUsers.jsx 构造:

<iframe
  width="560"
  height="315"
  src="https://<你的 ToolJet 域名>/applications/<slug>"
  title="ToolJet app - <slug>"
  frameborder="0"
  allowfullscreen
></iframe>

使用要点:

  • 嵌入链接与分享链接共用同一地址:/applications/<slug>,因此嵌入前同样需要先把应用设为公开并发布版本;
  • 尺寸可调:width/height 按你的页面布局修改,allowfullscreen 保留全屏能力;
  • iframe 显示条件:源码第 407 行表明,只有当 props.isPublic 为真或实例配置了 ENABLE_PRIVATE_APP_EMBED=true 时才会渲染嵌入链接区块——后者允许在私有(需登录)场景下仍可嵌入,具体是否启用取决于你的部署配置。

完整实战流程

综合官方文档与源码分析,从构建完成到对外可用的标准流程如下:

  1. 在编辑器中点击 Preview,在新标签页核对当前版本的应用表现(布局、数据源、交互);
  2. 对草稿满意后,发布(Release)当前版本;
  3. 点击右上角 Share 按钮打开分享对话框;
  4. 打开 Make the application public 开关,等待 "Application is now public." 提示;
  5. 在 slug 输入框自定义 URL(小写字母、数字、连字符,≤50 字符),等待 "Slug accepted!" 校验通过;
  6. 点击复制按钮获取分享链接(/applications/<slug>)并分发给用户;
  7. 如需嵌入官网/文档站,复制 iframe 代码粘贴到目标页面即可。

注意事项与适用前提

  • 公开 ≠ 无版本:对外可访问的是已发布版本,编辑中的草稿不会被公开访问;
  • 分支锁定:开启 Git 多分支后,默认分支的分享配置(公开开关、slug)被锁定,需切到功能分支修改;
  • 计划限制:ToolJet Cloud 的 Basic/Trial/Starter 计划不支持公开应用,自托管不受影响;
  • slug 变更影响:修改 slug 会改变分享与嵌入链接,请避免在链接已对外分发后随意更改。

延伸阅读

登录后查看全文
ToolJet