HarmonyOS WPS Open SDK 实践：统一版架构与 registerApp 调用链

用户093407773514
24 阅读5分钟

HarmonyOS 生态里，行业应用要在端内预览和编辑 Office 文档，WPS Open SDK 是常见选型。统一版发布后，专业版（ToB）与个人版（ToC）共用同一套 WPSApi 入口与 OpenFileRequest 参数模型——开发侧不再维护两套接口文档，差异集中在凭据形态、是否配置激活序列号，以及部分策略字段在 ToC 下是否生效。本文从工程架构角度总结统一版的价值：如何把注册、打开、策略、回传收成可复用的调用链，并在联调时用 ResultCode 做分层归因。

统一版解决了什么工程问题

以往常见痛点是：不同 WPS 客户端形态对应不同接入假设，业务代码里容易出现「打开页复制粘贴三份 Request 构造」。统一版把对外模型固定为：

HAR → registerApp → (ToB) setWpsFileToken → OpenFileRequest → sendRequest → Result
维度统一版目标态
API 入口单例 WPSApi
打开类型OpenFileRequest
结果模型Result + ResultCode
ToB 差异注册回调里 setWpsFileToken
ToC 差异注册 OK 即可打开，无需 SN

架构上建议拆两层：WpsBootstrap 负责注册与就绪标志；WpsOpenHelper 负责沙箱拷贝、构造 Request、处理 Promise。页面只依赖 sdkReady，避免生命周期里散落 registerApp。

registerApp：全链路门禁

对接文档硬性要求：registerApp 回调未到 ResultCode.OK 之前调用 sendRequest 会抛异常。这不是「打开失败」，而是链路未就绪。ToB 在成功回调里设置激活序列号；ToC 跳过 setWpsFileToken。

import {
  WPSApi,
  Result,
  ResultCode,
  SdkConstants,
} from '@wps/wps_sdk';

let sdkReady = false;

export function bootstrapWps(appKey: string, appSecret: string, proSn?: string): void {
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (r: Result) => {
      if (r.code !== ResultCode.OK) {
        console.error('register', r.code, r.msg);
        return;
      }
      if (!SdkConstants.isPersonalSdk() && proSn) {
        WPSApi.setWpsFileToken(proSn);
      }
      sdkReady = true;
    },
  });
}

export function isWpsReady(): boolean {
  return sdkReady;
}

Release 日志禁止打印完整 appSecret。调试包与正式包 bundleName 不同时，申请材料必须分开归档，否则 1013 会反复出现却被当成「偶现打不开」。

OpenFileRequest：按层叠加能力

统一版并不意味着一次打开就要写满所有字段。推荐联调顺序：

  1. 注册 OK + 沙箱路径只读打开
  2. enableEdit = true 验证可编辑
  3. 叠水印 / extraOptions
  4. 开 wpsTransferType 验证关窗回传
import { common } from '@kit.AbilityKit';
import {
  WPSApi,
  OpenFileRequest,
  TransferType,
  Result,
} from '@wps/wps_sdk';

export async function openWithTransfer(
  ctx: common.UIAbilityContext,
  path: string
): Promise<Result> {
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = true;
  req.wpsTransferType = TransferType.URI;
  return WPSApi.sendRequest(req);
}

ToB 不落地相关字段在 ToC 下可能无效——以对接文档标注为准，验收时不要跨形态假设 UI 一定变化。

ToB / ToC 差异速查（联调表）

步骤ToB（专业版）ToC（个人版）
registerApp必须必须
setWpsFileToken注册成功回调中设置不需要
OpenFileRequest.wpsToken不推荐，用全局 Token可忽略
enableLocalization控制不落地设置无效

用 SdkConstants.isPersonalSdk() 做运行时分支，而不是用包名猜测。全仓搜索 request.wpsToken 旧写法并清理，是统一版迁移的高频漏项。

ResultCode 与回传闭环

code === ResultCode.OK 且无 data 在未开回传时完全正常。回传开启后，fileUri 位于 WPS 沙箱，业务入库前必须拷贝；FD 回传关注 transferFd 与文件名、大小。把临时 URI 直接持久化，是联调后期最常见的闭环 bug。

错误分流顺序：HAR/Bundle → 注册 → 打开参数 → 回传拷贝。1013 出现时暂停参数实验，先对齐身份材料。

依赖集成、日志与协作收益

统一版仍以 HAR 交付，典型依赖段如下：

{
  "dependencies": {
    "@wps/wps_sdk": "file:./libs/wps_sdk.har"
  }
}

执行 ohpm install 后全量编译，确认业务代码 import 均来自 @wps/wps_sdk，而不是历史遗留的相对路径拷贝。工程结构上推荐三文件分工：WpsBootstrap.ts 只做注册与就绪标志；WpsOpenHelper.ts 负责沙箱拷贝、OpenFileRequest 构造与 Result 处理；页面组件只调用 openDocument(path, { editable })。这样统一版升级时，通常只需回归 bootstrap 与 helper，而不是全仓搜 registerApp 散落点。

Ability 启动阶段发起注册，避免用户点击「打开」时才首次注册导致首屏等待与竞态。若产品要求离线下也能看到「打开」按钮，可用 sdkReady === false 时禁用并展示「文档能力初始化中」，而不是静默失败后弹泛化错误。HAR 批次变更时，在 CHANGELOG 写清文件名与回归项：注册 OK、只读、可编辑、（若启用）回传落盘。

对团队而言，统一版还带来：参数表与错误码单一来源、预览/编辑/审批共用 WpsOpenHelper、ToB/ToC 各一套必测矩阵。联调阶段建议统一日志前缀 [WPS]，固定记录 register 的 code/msg、打开前后路径与结果。设备侧过滤 registerApp、1013、open non-ok、open exception。回传开启时在 resolve 分支记录 data 是否存在，并在拷贝完成后记录目标路径。

实践建议

Ability 启动阶段发起注册，页面消费就绪态。水印、extraOptions、不落地在同一打开封装内按验收追加，不要在多个页面分叉配置。出现打开异常时，先区分「未注册」与「打开非 OK」；前者修门禁，后者查路径与客户端。

HarmonyOS WPS Open SDK 统一版把「文档二开」从多套接口收敛成一条可重复的调用链。架构上守住注册门禁、Token 全局化、沙箱路径、回传落盘四条纪律，后续能力叠加会便宜很多。发版评审建议附上 HAR 文件名、Bundle 打印值、一次注册 OK 与一次成功打开日志，远程协助时可少问两轮。若本周只完成注册与只读打开，下周再按可编辑 → 策略字段 → 回传递增，每层保留成功与失败日志各一份。对接文档：365.kdocs.cn/l/clQl5cek2… ；技术支持：m_open_sdk@wps.cn ；技术交流 QQ 群：628436767。

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

avatar
文章
阅读
粉丝