在线协作表格接入实践

背景

业务场景是“测量数据在线协作编辑”：

旧流程：下载 Excel -> 本地修改 -> 重新上传；
新流程：在线多人协作编辑 -> 直接保存提交。

目标是减少文件流转成本，提升协作效率和数据时效性。

技术方案

本次采用第三方在线文档能力 WPS WebOffice 实现。
接入文档： WPS WebOffice

由于该能力涉及服务端接口（如文档标识、鉴权 token、回调能力等），需要前后端协同落地。仅前端无法独立完成完整链路。

前端接入流程

1. 初始化实例

const wpsInstance = ref();

wpsInstance.value = WebOfficeSDK.init({
  // 文档类型：表格
  officeType: WebOfficeSDK.OfficeType.Spreadsheet,
  // 应用 ID
  appId: "",
  // 文档 ID（通常由后端返回）
  fileId: "",
  // 用户鉴权 token（可使用业务 token）
  token: "",
  // 挂载容器，默认 body
  mount: "#excel-container",
  // 隐藏右下角帮助按钮
  commandBars: [
    {
      cmbId: "FloatQuickHelp",
      attributes: {
        visible: false,
        enable: false,
      },
    },
  ],
});

2. 监听文档事件

初始化后建议监听关键事件，确认文档打开状态和编辑状态：

wpsInstance.value.ApiEvent.AddApiEventListener("fileOpen", (data) => {
  // data.data 为 true 表示文件打开成功
  if (data.data) {
    // ...
  }
});

wpsInstance.value.ApiEvent.AddApiEventListener("fileStatus", (data) => {
  // 监听文件状态变化（编辑、保存等）
  console.log("文件状态变化：", data);
});

事件监听建议在 ready 之前注册，避免错过初始化阶段事件。

// ... 先注册监听
await wpsInstance.value.ready();

3. 执行保存

除快捷键 Ctrl + S 外，可提供业务保存按钮，统一触发保存逻辑：

const result = await wpsInstance.value.save();
// 返回结果字段可参考：
// https://solution.wps.cn/docs/web/instance.html#save

落地注意事项

若出现预览/编辑异常，通常需要先确认后端鉴权与文档接口是否正常；
前端需对 ready、fileOpen、save 结果做状态提示，避免用户误判；
建议增加保存成功/失败埋点，便于后续稳定性分析。

前后端协作分工

环节	前端职责	后端职责
文档创建	触发创建入口（如「新建测量表」按钮）	调用 WPS 开放平台接口创建文档，返回 `fileId`
鉴权	携带业务 token 发起初始化	生成/校验 WebOffice 所需的鉴权 token
权限控制	根据业务角色决定是否展示编辑入口	在文档权限层面控制只读/可编辑范围，避免仅靠前端隐藏按钮
保存回调	触发保存、展示保存状态	接收 WPS 保存回调（如有），落库或同步业务状态
异常兜底	展示统一的异常提示与重试入口	记录接口异常日志，便于排查签名/权限问题

常见问题排查

现象	可能原因	排查方向
容器空白，`fileOpen` 未触发	`appId`/`fileId`/`token` 任一参数无效	检查初始化参数是否与后端返回值一致，浏览器控制台是否有跨域或鉴权报错
打开后无法编辑	文档权限被后端设置为只读	与后端确认当前用户在文档层面的权限配置
保存无响应或报错	`token` 过期，或网络中断	检查 `save()` 返回结果与错误信息，必要时刷新 token 后重试
多人编辑时看不到对方变更	依赖 WPS 协同能力是否正确启用	确认接入的文档类型与套餐是否支持多人实时协同

回归检查清单

新建文档、打开已有文档两条路径均可正常加载出表格内容；
多人同时打开同一文档编辑，变更可以实时同步展示；
手动点击保存按钮与 Ctrl + S 快捷键均可正常触发保存并给出成功提示；
网络异常/token 过期场景下，页面有明确的错误提示而非静默失败；
只读权限用户打开文档时，编辑相关操作被正确禁用。

在线协作表格接入实践

在线协作表格接入实践

背景

技术方案

前端接入流程

1. 初始化实例

2. 监听文档事件

3. 执行保存

落地注意事项

前后端协作分工

常见问题排查

回归检查清单

相关链接

team documents