【鸿蒙二开】WPS Open SDK registerApp 注册要点

HarmonyOS 应用要在端内打开 Word、Excel、PPT，常见路径是集成 WPS Open SDK 鸿蒙统一版：一套 WPSApi 覆盖专业版（ToB）与个人版（ToC）。无论哪种形态，registerApp 都必须成功，之后才能 sendRequest。ToB 还要在成功回调里 setWpsFileToken；ToC 注册 OK 即可打开，无需序列号。社区联调里最常见的两类现象是：未等回调就打开导致抛异常，以及包名与凭据不一致落到 1013。本文按交流帖口径压缩成要点、最小代码与排查清单。

统一版里注册解决什么问题

对接文档：https://365.kdocs.cn/l/clQl5cek2NoT

最小代码

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

WPSApi.registerApp(APP_KEY, APP_SECRET, {
  onCallback: (r) => {
    if (r.code !== ResultCode.OK) {
      console.error(r.code, r.msg);
      return;
    }
    if (!SdkConstants.isPersonalSdk()) {
      WPSApi.setWpsFileToken(PRO_SN);
    }
    // ready 后再 sendRequest
  },
});

打开侧：

const req = new OpenFileRequest(ctx, sandboxPath);
await WPSApi.sendRequest(req);

未注册成功就打开，Promise 会 reject，这不是「打开失败」，先修门禁。

必测对照

能力叠加顺序

1. 注册 OK + 只读打开

2. enableEdit = true 可编辑

3. 水印 / extraOptions

4. wpsTransferType 关窗回传

回传开启后，必须把 WPS 沙箱 URI 拷贝到本应用沙箱。ToC 上部分 ToB 专属字段设置无效，以文档标注为准。

联调清单

1. 冷启动注册 OK

2. Bundle 与凭据对齐

3. 只读 / 可编辑各验一次

4. ToB 确认 setWpsFileToken；全仓清理 request.wpsToken

5. 回传落盘

6. 1013 出现时暂停参数实验

调试包与正式包 Bundle 不同时，申请归档必须分开。路径类型不一致时先拷贝再传入 OpenFileRequest。全仓搜 wpsToken，清掉 Request 上的旧写法。

现象对照

• 「未注册」当 SDK 缺失：其实是门禁未就绪

• 「只能只读」当能力不够：其实默认未设 enableEdit

• 「回传成功但文件打不开」：URI 未拷贝

• 「参数在当前交付不生效」：用文档参数表和日志，不要跨形态假设 UI 一定变化

能力叠加建议：注册成功 → 只读打开 → 可编辑 → 水印 / extraOptions → 回传；不要在注册失败时先调水印。发版评审写明负责人与文件路径，避免同事再次把 registerApp 写回业务页生命周期。

获取与小结

统一版价值是一套 API 覆盖双形态，工程纪律才是稳定体验的关键：守住注册门禁、Token 全局化、沙箱路径、回传落盘。出现 1013 时优先对齐 Bundle 与申请归档；若注册不到 OK 不要并行打开。发版评审建议附上 HAR 文件名与一次冷启动注册日志。HAR 升级周先只替换依赖并重跑注册与只读打开，确认身份无回归再恢复高级参数。

更多参数见官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT

申请 SDK HAR 与凭据：m_open_sdk@wps.cn（注明包名与专业版/个人版需求）。

技术交流 QQ 群：628436767