前端 iframe 嵌入

通过 iframe 嵌入 DocFlow 后，您可以在自己的系统中直接展示文档列表、文件详情、审核任务等页面，无需用户单独打开 DocFlow。接入前请先通过 API 获取有效的 token，并在 iframe 的 URL 中携带。

本文介绍两种接入方式：快捷接入（直接使用接口返回的详情页 URL）和通用接入（自行拼接 URL 并携带 token）。同时说明父页面与 iframe 的 postMessage 通信、以及多 iframe 场景下的 Token 隔离机制。

接入流程概览

快捷接入：适用于只需展示「文件详情页」或「审核详情页」的场景，调用接口获取 task_detail_url 后直接嵌入 iframe。
通用接入：适用于需要嵌入首页、空间配置、文档列表等任意 DocFlow 页面的场景，需先调用接口生成用户 token，再在访问地址中携带 token 参数。

快捷接入方式

针对文件详情页和审核详情页，支持通过接口直接获取可嵌入的 URL。

调用对应接口获取 task_detail_url 字段：
- 文件详情页：参见 REST API 文档中获取文件详情页 URL相关接口。
- 审核详情页：参见 REST API 文档中获取审核详情页 URL相关接口。
将返回的 task_detail_url 作为 iframe 的 src 即可嵌入使用。

无需再单独传 token，该 URL 已包含鉴权信息。

通用接入方式

第一步：生成用户 Token

通过调用生成短时间有效 token API，获取当前用户的有效 token。
接口说明请参见 REST API 文档。

第二步：携带 Token 访问 DocFlow 页面

在 iframe 的 src 中访问 DocFlow 前端页面时，在 URL 上加上 token=xxx 参数。
以下以公有云域名 https://docflow.textin.com 为例，私有化部署请替换为实际域名。注意：所有 DocFlow 前端 URL 均支持在查询参数中追加 token，用于身份校验。

访问首页

<iframe src="https://docflow.textin.com?token=xxx" referrerpolicy="origin" />

访问指定空间

<iframe src="https://docflow.textin.com/workspace/configure?workspaceIdNo=xxx&token=xxx" referrerpolicy="origin" />

访问文件详情页

直接访问：

<iframe src="https://docflow.textin.com/documents/detail-new?workspaceIdNo=xxx&id=xxx&resultId=xxx&token=xxx" referrerpolicy="origin" />

精简模式（隐藏部分跳转入口）：

<iframe src="https://docflow.textin.com/documents/detail-new?workspaceIdNo=xxx&id=xxx&resultId=xxx&token=xxx&mode=minimal" referrerpolicy="origin" />

访问审核任务详情页

直接访问：

<iframe src="https://docflow.textin.com/review/task/task-detail?workspaceIdNo=xxx&id=xxx&token=xxx" referrerpolicy="origin" />

精简模式（隐藏部分跳转入口）：

<iframe src="https://docflow.textin.com/review/task/task-detail?workspaceIdNo=xxx&id=xxx&token=xxx&mode=minimal" referrerpolicy="origin" />

父页面集成示例

在父页面中嵌入 iframe，并监听来自 DocFlow 的 postMessage 事件（如 token 过期、登录、退出、权限不足等），便于刷新 token 或提示用户。

<iframe
  id="docflow-iframe"
  src="https://your-domain.com/documents/list?token=YOUR_TOKEN"
  allow="clipboard-read; clipboard-write"
  referrerpolicy="origin"
></iframe>

<script>
const iframeOrigin = 'https://your-domain.com';

window.addEventListener('message', (event) => {
  if (event.origin !== iframeOrigin) return;

  const { type, data } = event.data || {};

  switch (type) {
    case 'tokenExpired':
      console.warn('Token 已过期，请重新获取并刷新 iframe');
      break;
    case 'login':
      console.log('用户已登录');
      break;
    case 'logout':
      console.warn('用户已退出登录');
      break;
    case 'noPermission':
      console.warn('权限不足');
      break;
    case 'error':
      console.error('发生错误', data);
      break;
  }
});
</script>

附加说明

postMessage 通信协议

iframe 内的 DocFlow 页面会向父窗口发送以下类型的消息，父页面可通过 window.addEventListener('message', ...) 接收并处理。

消息类型	说明	触发时机
`tokenExpired`	Token 已失效	API 返回 401 时
`login`	用户登录成功	Token 认证成功时
`logout`	用户退出登录	用户主动退出时
`noPermission`	权限不足	API 返回权限错误时
`error`	发生错误	通用错误通知

消息格式：

interface IframeMessage {
  type: 'tokenExpired' | 'login' | 'logout' | 'noPermission' | 'error';
  data?: unknown;
}

Token 隔离机制

当同一浏览器中存在多个不同父页面嵌入的 DocFlow iframe 时，系统会按「来源」隔离各自的用户状态，避免 Token 冲突。该机制依赖 Referrer 信息（即 document.referrer 或父页面的 origin）。接入方必须满足以下二选一：
1）Referrer 策略允许传递 origin；或
2）使用同源策略（父子同源）。

推荐配置方式： 方式一：iframe 属性（推荐）

<iframe
  src="https://docflow.textin.com/documents/list?token=YOUR_TOKEN"
  referrerpolicy="origin"
></iframe>

方式二：HTML meta 标签 在父页面 <head> 中添加：

<meta name="referrer" content="origin">

方式三：HTTP 响应头 在父页面所在域名的 HTTP 响应中设置：

Referrer-Policy: origin

产品概览

MCP&Skill

场景化示例

工作空间管理

文件类别管理

文档上传

文档解析

文档分类

文档拆分

文档抽取

智能审核

文档删除

文档重试

Web 页面集成

常见问题

接入流程概览

快捷接入方式

通用接入方式

第一步：生成用户 Token

第二步：携带 Token 访问 DocFlow 页面

访问首页

访问指定空间

访问文件详情页

访问审核任务详情页

父页面集成示例

附加说明

postMessage 通信协议

Token 隔离机制

​接入流程概览

​快捷接入方式

​通用接入方式

​第一步：生成用户 Token

​第二步：携带 Token 访问 DocFlow 页面

​访问首页

​访问指定空间

​访问文件详情页

​访问审核任务详情页

​父页面集成示例

​附加说明

​postMessage 通信协议

​Token 隔离机制

接入流程概览

快捷接入方式

通用接入方式

第一步：生成用户 Token

第二步：携带 Token 访问 DocFlow 页面

访问首页

访问指定空间

访问文件详情页

访问审核任务详情页

父页面集成示例

附加说明

postMessage 通信协议

Token 隔离机制