跳转到主要内容
通过 iframe 嵌入 DocFlow 后，您可以在自己的系统中直接展示文档列表、文件详情、审核任务等页面，无需用户单独打开 DocFlow。接入前请先通过 API 获取有效的 token，并在 iframe 的 URL 中携带。
本文介绍两种接入方式：快捷接入（直接使用接口返回的详情页 URL）和通用接入（自行拼接 URL 并携带 token）。同时说明父页面与 iframe 的 postMessage 通信、以及多 iframe 场景下的 Token 隔离机制。

​
接入流程概览

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

​
快捷接入方式

针对文件详情页和审核详情页，支持通过接口直接获取可嵌入的 URL。
  1. 调用对应接口获取 task_detail_url 字段：
  2. 将返回的 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', ...) 接收并处理。
消息类型说明触发时机
tokenExpiredToken 已失效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