【鸿蒙二开】WPS registerApp 注册门禁与 1013 排查

鸿蒙应用接入 WPS Open SDK 后，registerApp 是文档打开链路的首要门禁。注册回调没有返回 ResultCode.OK 时，sendRequest 不具备执行条件，常见表现就是 Promise 直接抛异常。社区里遇到“文档打不开”时，建议先看注册结果，再看文件路径、编辑模式和水印参数，避免把初始化问题误判成文档参数问题。

一、注册完成才算 SDK 就绪

WPSApi.registerApp(appKey, appSecret, callback) 使用 WPS 签发的接入凭据，在本地完成应用资格校验。凭据与申请时的 Bundle 包名绑定，调试包和正式包的包名不同，就需要分别确认是否覆盖。注册成功后再构造 OpenFileRequest，顺序不要反：

HAR → registerApp → ResultCode.OK → OpenFileRequest → sendRequest

页面可以把“WPS 初始化中”和“文档打开失败”做成两个状态。前者等待注册完成，后者才去检查沙箱路径和文档能力。

二、最小注册代码

不要在每次点击“打开”时重新注册。用一个共享 Promise 合并并发调用，失败后再允许重试：

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

let ready = false;
let booting: Promise<void> | null = null;

export function initWps(
  appKey: string,
  appSecret: string,
  activationSn?: string
): Promise<void> {
  if (ready) return Promise.resolve();
  if (booting) return booting;

  booting = new Promise<void>((resolve, reject) => {
    WPSApi.registerApp(appKey, appSecret, {
      onCallback: (result: Result) => {
        if (result.code !== ResultCode.OK) {
          booting = null;
          reject(new Error(`register ${result.code}: ${result.msg ?? ''}`));
          return;
        }
        if (activationSn) {
          WPSApi.setWpsFileToken(activationSn);
        }
        ready = true;
        resolve();
      },
    });
  });

  return booting;
}

日志里记录 code 和 msg 即可，不要打印完整 appSecret。打开侧先等待 initWps()，再执行 sendRequest；未就绪时不要并发发起多个文档请求。

三、两种形态的序列号差异

需要激活序列号时，推荐在注册成功回调中调用 WPSApi.setWpsFileToken(token)，一次设置后对后续请求生效。不要在 OpenFileRequest.wpsToken 上重复赋值。全仓检索旧写法，可以避免两处配置同时存在导致排查困难。

四、1013 先对包名，不要先改参数

1013 对应 ERROR_CODE_AUTH_FAILURE，含义是接入凭据校验失败。遇到它时，建议先停下来完成这张对照表：

如果是 key 或 secret 为空，通常更接近 ResultCode.ERROR；1013 则优先排查身份不一致。此时继续调整水印、修订或回传参数，通常不会改善结果。建议先做一次最小验证：注册成功加只读打开，通过后再逐项恢复文档能力。

五、联调清单

1. 冷启动确认 registerApp 返回 ResultCode.OK。

2. 确认当前包名与申请凭据时的包名一致。

3. 需要序列号的交付，在成功回调中完成 setWpsFileToken。

4. 清理 OpenFileRequest.wpsToken 的重复写法。

5. 先用沙箱文件验证只读打开，再开启可编辑模式。

6. 更换 HAR 或包名后，从注册环节重新回归。

把注册收成应用级门禁后，页面只关心“是否就绪”，文档 helper 只关心“如何打开”，1013 和未注册异常就能分别定位。对于鸿蒙 WPS 二开项目，这比在每个业务页复制一份注册代码更稳定，也更容易在 SDK 升级时完成回归。