Skip to main content

研发必看

本文档列举了 SDK 集成过程中最常见的问题和注意事项，建议在开始集成前仔细阅读。

1. 必须配置白名单​

⚠️ 这是最重要的配置，未配置将无法调用任何 API

要想与挂载的文档进行通信，能够调用 API 操作文档，必须进行白名单配置，否则文档会拒绝响应 API 请求。

在 zdocs.env 文件中添加：

LS_WEBRESOURCE_WHITEORIGINS=http://172.16.22.99:8001

白名单配置要点：

  • 多个地址用逗号分割：LS_WEBRESOURCE_WHITEORIGINS=http://172.16.22.99:8001,http://172.16.22.99:8002
  • 地址格式为：协议 + IP/域名 + 端口（与跨域标准一致）
  • 域名访问时使用：http://www.test.com（不加端口）
  • 默认端口（80/443）不需要加端口号：http://172.16.22.99
  • 测试阶段可设置：LS_WEBRESOURCE_WHITEORIGINS=* 来适配任何三方

2. 使用匹配的 SDK 脚本​

⚠️ 强烈建议使用与部署的 FilezOffice 服务匹配的 SDK 脚本文件

获取方式：

  1. 访问 http://xxx/docs/version 获取 clientTimeStamp
  2. 访问 http://xxx/docs/static/${clientTimeStamp}/sdk.js 下载对应版本的 SDK

3. 快速集成演示环境​

💡 如果是第一次接触 FilezOffice，可以先参考完整的入门指南快速验证集成效果

完整步骤包括：

  • 获取演示环境版本信息和 SDK 文件
  • 配置白名单和引用 SDK
  • 挂载文档并处理常见问题

详细教程：如何快速集成演示环境文档

这个教程会帮助你快速搭建第一个集成示例，验证整个流程的可行性。

4. 确保挂载节点存在​

调用 ZOfficeSDK.mount 时，必须确保页面上已经存在对应的 DOM 节点，否则会报错：No element found for the selector "#xxx"

重要提示：

  • mount(url, selector) - selector 是文档挂载的容器节点，SDK 会在其下创建 iframe
  • connect(selector) - selector 是iframe 的父节点（不是 iframe 本身）
// ❌ 错误：DOM 还未就绪
ZOfficeSDK.mount(url, '#doc1', true);

// ✅ 正确：确保 DOM 已存在
window.onload = async function() {
  const app = await ZOfficeSDK.mount(url, '#doc1', true);
  await app.ready();
}
<!-- mount 示例 -->
<div id="doc1"></div>  <!-- SDK 会在这个 div 下创建 iframe -->

<!-- connect 示例 -->
<div id="doc1">        <!-- selector 指向这个 div -->
  <iframe src="..."></iframe>  <!-- 不是指向 iframe 本身 -->
</div>

5. 必须等待 app.ready()​

⚠️ 调用任何文档 API 之前，必须确保文档已就绪

推荐将 mount/connect 的第三个参数 bAsync 设置为 true，并使用 await app.ready() 等待文档加载完成：

const app = await ZOfficeSDK.mount(url, '#doc1', true);
await app.ready(); // ⚠️ 必须等待，否则后续 API 调用可能失败

好处：

  • 在文档内容加载完成之前更早地返回可用的 Application 对象，避免 mount 等待时间过长
  • 通过 app.ready() 精确控制等待时机，只在需要调用 API 时才等待
  • 提升用户体验，可以在文档加载过程中先展示加载状态

6. 遇到问题时的排查步骤​

⚠️ 遇到错误时，请先查看浏览器控制台的错误信息

SDK 在遇到问题时会在浏览器控制台输出详细的错误信息。您可以：

  1. 打开浏览器开发者工具（F12）
  2. 查看 Console 标签页中的错误信息
  3. 复制关键错误信息
  4. 在 常见问题 FAQ 中查找对应的解决方案

常见错误示例：

7. 验证文档 URL 可访问性​

如果 mount/connect 后遇到错误，首先验证文档 URL：

排查方法：将传入的 URL 复制到浏览器新标签页中打开，确认：

  • URL 格式正确
  • 文档能正常加载显示
  • 没有 404 或其他错误

如果 URL 无法打开，问题与 SDK 无关，需要先解决文档访问问题。

8. mount vs connect 的选择​

  • mount：SDK 会自动创建 iframe 并挂载文档，能完整监控文档加载生命周期
  • connect：连接已存在的 iframe，可能无法捕获文档加载过程中的错误

建议：优先使用 mount 方法，它能提供更好的错误提示和生命周期管理。

9. iframe 缓存问题​

在 Vue/React 等框架中，如果对 iframe 做了缓存，非首次打开文档时可能无法调用 API（报 timeout 错误）。

解决方案：每次打开文档时，重新调用 ZOfficeSDK.connect 建立连接：

// 每次打开文档前重新建立连接
const app = await ZOfficeSDK.connect('#doc1', true);
await app.ready();

10. 跨域登录问题​

在 Chrome/Edge 高版本中，由于跨域限制，可能出现挂载文档后停留在登录页面的问题。

解决方案：

  • 使用 Firefox 浏览器测试
  • 配置 Nginx 反向代理，将测试页面和文档服务代理到同一域名下

11. 隐藏文档的正确方式​

需要隐藏 FilezOffice 文档时：

  • ✅ 推荐使用：visibility: hidden;
  • ❌ 禁止使用：display: none;

原因：display: none; 会导致文档无法正确初始化。

12. UI 组件配置​

mount 方法支持第四个参数配置文档初始 UI 显示状态：

const app = await ZOfficeSDK.mount(url, '#doc1', true, {
  uiConfig: {
    WordCommentMark: 'defaultInvisible',   // 隐藏批注标记
    WordRevisionMark: 'defaultInvisible',  // 隐藏修订标记
    Bookmark: 'defaultInvisible',          // 隐藏书签标记
    NaviPanel: 'defaultInvisible',         // 默认收起导航栏
    RevisionActions: 'forceInvisible'      // 隐藏修订接受&拒绝按钮
  }
});

也可以通过 URL 参数配置：

http://xxx/docs/app/xxx?WordCommentMark=defaultInvisible&Bookmark=defaultInvisible

更多问题请参考 常见问题 FAQ

Last updated on