HarmonyOS WPS Open SDK 二开指南：关闭回传与沙箱路径拷贝实践

用户093407773514
0 阅读5分钟

三方应用在 HarmonyOS 上嵌入 WPS，往往把精力放在 registerApp 和 OpenFileRequest 的打开参数上，却忽略了用户关窗之后的「最后一公里」——编辑结果如何回到应用进程。WPS Open SDK 通过关闭回传（Transfer）机制，把这一环标准化为 sendRequest 的异步结果。本文面向架构与实现同学，梳理 URI/FD 两种回传、回调状态机，以及 filePath 落盘策略。与只读预览不同，可编辑且需回写的场景在政务、金融、制造 MES 等条线里占比很高，回传设计应尽早纳入技术方案评审。

业务闭环中的位置

典型文档二开时序可以概括为：

应用沙箱文件 → OpenFileRequest → WPS 编辑 → 用户关闭
                                              ↓
                              Result.data (URI 或 FD)
                                              ↓
                              拷贝/读入本应用沙箱 → 业务上传/持久化

若未配置 enableTransferFile 或 wpsTransferType，sendRequest 在 WPS 成功拉起后即可 resolve，此时 data 为空——适合纯预览、不要求回写业务的场景。一旦产品要求「编辑后回传」，必须在请求对象上显式打开回传，并在 Promise 链中处理 ResultData。

参数模型与优先级

OpenFileRequest 上与回传相关的字段：

  • enableTransferFile?: boolean — 为 true 时按 URI 方式回传；
  • wpsTransferType?: TransferType — TransferType.URI 或 TransferType.FD，优先于 enableTransferFile。

工程上建议统一只设 wpsTransferType，减少「两个开关谁生效」的歧义。enableEdit 与回传独立：只读打开也可配置回传（若业务需要），但多数可编辑场景会同时开启编辑与回传。与 extraOptions、水印、修订模式等参数一样，回传参数挂在同一 OpenFileRequest 实例上，在 registerApp 完成之后构造请求即可，无需额外注册步骤。团队内可维护一份「打开模板」工厂方法，按场景（预览 / 编辑不回传 / 编辑回传 URI / 编辑回传 FD）生成请求，降低业务方误用概率。

Result 与 ResultData 语义

WPSApi.sendRequest 返回 Promise<Result>。与回传相关的判断逻辑：

场景codedata
未开回传，拉起成功OK空
开启回传，用户关闭且成功OK含 fileUri 或 transferFd 等
拉起失败或回传失败非 OK视情况为空或带错误信息

ResultData 中与文件相关的核心字段：

  • fileUri：URI 模式路径（WPS 沙箱内）；
  • transferFd、transferFileName、transferFileSize：FD 模式；
  • parameters：扩展字典，FD 场景可能嵌套 transferFd 的 type/value。

实现层应把「打开成功」与「拿到回传文件」拆成两个分支，避免 UI 提前提示「保存成功」而实际未收到 data。在 UI 层可以增加「等待 WPS 关闭」的状态提示，减少用户过早返回应用导致的空回调。对于需要把回传文件立刻上传的场景，建议在拷贝完成后再 dismiss 加载框，并把上传失败与回传失败分开提示，便于客服定位问题。

URI 与 FD 回传实现

URI 模式：fileUri 指向 WPS 维护的临时文件。三方应用使用 @ohos.file.fs 只读打开，再 copyFileSync 到例如 context.filesDir/wps_callback/ 下，最后用 fileuri.getUriFromPath 转为业务使用的 URI。不要把 fileUri 直接存入业务数据库；拷贝前 mkdirSync；专业版不落地时拷贝后可 unlink WPS 临时文件。拷贝时建议保留原扩展名，便于后续 MIME 判断与服务器校验。

FD 模式：从 transferFd 分块 readSync 写入本应用沙箱，写完后 close fd，并校验 transferFileSize。适合减少路径字符串暴露的场景。读缓冲大小可按设备内存调整，避免一次读入过大数组。两种模式建议封装为统一的 resolveCallbackFilePath(context, result)，业务层只关心最终路径，并可为该函数编写单元测试，用 Mock Result 覆盖空 data、仅 URI、仅 FD 等分支。

下面给出统一入口骨架，内部按 FD 优先、URI 次之，与官方 Demo 的 handleCallbackData / handleCallbackDataByFd 对齐：

import { common } from '@kit.AbilityKit';
import {
  WPSApi,
  OpenFileRequest,
  TransferType,
  ResultCode,
  Result,
} from '@wps/wps_sdk';

async function openWithTransfer(
  ctx: common.UIAbilityContext,
  path: string,
  mode: TransferType = TransferType.URI
): Promise<string | undefined> {
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = true;
  req.wpsTransferType = mode;

  const result = await WPSApi.sendRequest(req);
  if (result.code !== ResultCode.OK) {
    throw new Error(result.msg);
  }
  return resolveCallbackFilePath(ctx, result);
}

resolveCallbackFilePath 内部按 FD 优先、URI 次之合并逻辑即可。拷贝完成后可将路径交给上传模块或事件总线，避免在 UI 组件里散落 fs 操作，方便后续做单元测试与 Mock。

版本差异、排错与上线建议

统一版 SDK 接口一致，关闭回传在专业版与个人版均可使用。专业版叠加不落地时，拷贝与清理策略更要严格；个人版 HAR 须与申请凭据匹配。常见故障：回调无 data（未设 wpsTransferType 或用户未关文档）、拷贝失败（权限/占用/空间）、FD 泄漏、仍用打开前 path 上传。

上线前建议在测试包打开详细日志，生产仅记录 code 与文件名。大文件优先在弱网环境试上传，确认回传拷贝不阻塞主线程（可放 TaskPool）。与 extraOptions、水印等参数可同时配置在同一 OpenFileRequest 上，互不影响。

小结

关闭回传让 HarmonyOS WPS 二开从「单向打开」升级为「可回写闭环」。架构上应固定「回调解析 → 沙箱拷贝 → 业务消费」三层，URI/FD 仅作为传输层差异。统一版 WPS Open SDK 有利于 ISV 用一套实现服务 ToB/ToC 多场景，也便于在需求变更时仅调整 wpsTransferType 而不重写业务上传链路。后续若接入断点续传或加密上传，只需替换「业务消费」层，回传解析层可保持稳定，从而降低回归成本。也建议在代码评审中单独检查：所有 sendRequest 调用是否处理了 data 为空与非空两种成功路径，这是 WPS 二开里很容易被忽略的边界条件。

基于 WPS Open SDK 鸿蒙版实践整理，仅供开发者交流参考。
官方对接文档：365.kdocs.cn/l/clQl5cek2…
开发者交流 QQ 群：628436767

avatar
文章
阅读
粉丝