Skip to main content

如何快速集成演示环境文档

场景说明​

使用 FilezOffice 文档中台私有部署的演示环境，将演示环境中的在线编辑页面快速集成到业务系统中，预览集成效果。

集成步骤​

步骤 1：获取文档中台版本信息​

访问文档中台的版本接口，确认服务可用并获取版本信息。

接口地址：

http://{文档中台IP}/docs/version

示例：

# 假设文档中台地址为 http://172.16.22.98
curl http://172.16.22.98/docs/version

返回示例：

{
  "version": "v8.0.5.0",
  "productName": "FilezOfficeoffice-integration",
  "clientTimeStamp": "20260201165206",
  "swcoreTimestamp": "20260201161355",
  "description": "FileFilezOffice v8.0 release",
  "serverTimestamp": "20260201163716",
  "ifixVersion": 5
}

关键字段：clientTimeStamp - 用于后续获取 SDK 文件

步骤 2：获取 SDK 脚本文件​

根据版本信息中的 clientTimeStamp 获取匹配的 SDK 文件。

详细说明：SDK 脚本文件获取

SDK 文件地址：

http://{文档中台IP}/docs/static/{clientTimeStamp}/sdk.js

示例：

<!-- 引用 SDK 文件 -->
<script src="http://172.16.22.98/docs/static/20260201165206/sdk.js"></script>

可用的 SDK 包格式：

  • sdk.js - 非模块化包（推荐浏览器直接引用）
  • sdk.esm.js - ESM 模块包
  • sdk.cjs.js - CommonJS 包

关于 SDK 自动更新​

问题：文档中台每次升级后，SDK 的 clientTimeStamp 会变化，如果使用固定的 SDK 地址，需要手动更新代码并重新部署业务系统。

建议：可以考虑实现 SDK 动态加载，通过先请求 /docs/version 接口获取最新的 clientTimeStamp，再动态加载对应版本的 SDK 文件，从而实现 SDK 自动跟随文档中台版本更新。

优点：

  • ✅ 文档中台升级后，SDK 自动跟随更新
  • ✅ 无需手动修改代码和重新部署业务系统
  • ✅ 始终保持 SDK 与服务版本匹配

注意：此方案仅为建议，实际使用前需要根据业务场景验证可行性。

步骤 3：获取文档链接​

从演示环境获取要集成的文档链接。

文档链接格式：

http://{文档中台IP}/docs/app/{类型}/{文档ID}/edit/content

示例：

http://172.16.22.98/docs/app/local/752740ad-9417-45b2-a3bc-c116b179b08c/edit/content

步骤 4：引用 SDK 到业务系统​

在业务系统的 HTML 页面中引用 SDK 文件。

详细说明：SDK 引用方式

示例：

<!DOCTYPE html>
<html>
<head>
  <title>FilezOffice 集成示例</title>
  <style>
    #doc-container {
      width: 100%;
      height: 600px;
    }
  </style>
</head>
<body>
  <h1>文档编辑区域</h1>
  <div id="doc-container"></div>

  <!-- 引用 SDK -->
  <script src="http://172.16.22.98/docs/static/20260201165206/sdk.js"></script>
  
  <script>
    // 在这里调用 SDK API
  </script>
</body>
</html>

步骤 5：挂载文档​

使用 SDK API 挂载文档到页面容器中。

详细说明：挂载文档 API

完整示例代码：

<!DOCTYPE html>
<html>
<head>
  <title>FilezOffice 集成示例</title>
  <style>
    #doc-container {
      width: 100%;
      height: 600px;
      border: 1px solid #ccc;
    }
  </style>
</head>
<body>
  <h1>文档编辑区域</h1>
  <div id="doc-container"></div>

  <!-- 引用 SDK -->
  <script src="http://172.16.22.98/docs/static/20260201165206/sdk.js"></script>
  
  <script>
    async function mountDocument() {
      try {
        // 文档地址
        const docUrl = 'http://172.16.22.98/docs/app/local/752740ad-9417-45b2-a3bc-c116b179b08c/edit/content';
        
        // 挂载文档
        const app = await ZOfficeSDK.mount(
          docUrl,
          '#doc-container',
          true  // enableIframeConnect: 启用 iframe 通信
        );
        
        // 等待文档加载完成
        await app.ready();
        
        console.log('文档挂载成功');
        
        // 可以调用 API 操作文档
      } catch (error) {
        console.error('文档挂载失败:', error);
      }
    }
    
    // 页面加载后挂载文档
    window.onload = mountDocument;
  </script>
</body>
</html>

步骤 6：处理本地开发环境登录问题​

挂载文档后，如果 iframe 一直停留在登录页面无法进入编辑界面，这是本地开发环境的常见问题。

问题原因：高版本浏览器对跨域有严格限制。

解决方案：

方案一：使用 Firefox 浏览器​

Firefox 对跨域的限制相对宽松。

方案二：配置 Nginx 反向代理​

通过 Nginx 将文档中台代理到本地环境的同域下，解决跨域问题。

详细说明：参考 本地开发挂载文档失败

注意事项​

1. 白名单配置​

集成前需要在文档中台配置业务系统的白名单，否则无法建立通信。

详细说明：配置有效的白名单

示例：

# 在文档中台服务器的 zdocs.env 文件中添加
LS_WEBRESOURCE_WHITEORIGINS=http://172.16.22.99:8001

2. 本地开发登录问题​

本地开发环境挂载文档后，如果遇到登录页面问题，请参考"步骤 6"的说明。

详细解决方案：本地开发挂载文档失败

3. SDK 版本匹配​

  • SDK 文件必须与文档中台版本匹配
  • 使用 clientTimeStamp 确保版本一致

4. 网络访问​

  • 确保业务系统能访问文档中台的网络地址

快速检查清单​

在集成前，请确认以下事项：

  • 获取到有效的文档链接
  • 在文档中台配置了业务系统白名单
  • 业务系统与文档中台网络互通

相关文档​

Last updated on