HarmonyOS 应用要在端内预览或编辑 Office 文档，常见路径是集成 WPS Open SDK，以 HAR 形式接入 @wps/wps_sdk。业务页往往直接构造 OpenFileRequest 再调用 WPSApi.sendRequest，却忽略对接文档的硬性时序：registerApp 回调未到 ResultCode.OK 之前发起打开，会抛异常而不是返回打开失败。本文把注册当成独立接入层来写：何时调用、如何读 Result、1013 怎么分流，以及如何把就绪标志从页面生命周期里抽出来。字段语义以官方对接文档为准。

一、注册在调用链中的位置

典型时序固定为：集成 HAR → 启动阶段 registerApp →（按凭据约定）可选 setWpsFileToken → 构造 OpenFileRequest → WPSApi.sendRequest。注册不是「打开文档的附属步骤」，而是整条链路的门禁。未就绪时继续打开，日志里常见的是 Promise reject，而不是 Result.code 为非 0。

层级	职责	主要入口
依赖层	HAR、凭据、包名绑定	@wps/wps_sdk
接入层	应用注册、按需激活序列号	registerApp / setWpsFileToken
打开层	沙箱路径、只读或可编辑	OpenFileRequest / sendRequest
结果层	成功、非 OK、异常	Result / ResultCode

接入凭据 appKey 与 appSecret 和运行时 bundleName 绑定，校验在本地完成。换 flavor 或换 HAR 批次后，应重新核对这三项是否仍与申请归档一致，再谈打开参数。

二、registerApp 的调用约定

官方入口是 WPSApi.registerApp(appKey, appSecret, callback)。回调参数是 Result：读 code 与 msg，不要只判断「有没有回调」。appKey、appSecret 为空时，常见结果是 ResultCode.ERROR 并提示参数不完整；凭据与包名不匹配时，常见结果是 1013（ResultCode.ERROR_CODE_AUTH_FAILURE）。

建议在 Ability 启动阶段发起注册，而不是用户点击「打开」时才首次调用。冷启动注册可以把等待从点击路径挪到启动路径，页面只消费 sdkReady。Release 日志禁止打印完整 appSecret。

现象	倾向原因	处理
ResultCode.ERROR	参数为空或不完整	检查 key / secret 是否写入
1013	凭据或包名不匹配	对照 Bundle 打印值与申请归档
回调未到 OK 就打开	时序错误	先修门禁，再调 sendRequest
Promise 抛异常	尚未注册成功	与打开非 OK 分开处理

三、就绪门禁封装

把注册收成独立模块，避免每个打开页复制一份回调。需要激活序列号时，只在 ResultCode.OK 分支调用 setWpsFileToken，不要写到 OpenFileRequest.wpsToken。

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

let sdkReady = false;

export function bootstrapWps(
  appKey: string,
  appSecret: string,
  activationSn?: string
): Promise<void> {
  return new Promise((resolve, reject) => {
    if (sdkReady) {
      resolve();
      return;
    }
    WPSApi.registerApp(appKey, appSecret, {
      onCallback: (r: Result) => {
        if (r.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
          reject(new Error(`1013:${r.msg ?? ''}`));
          return;
        }
        if (r.code !== ResultCode.OK) {
          reject(new Error(`register ${r.code}:${r.msg ?? ''}`));
          return;
        }
        if (activationSn) {
          WPSApi.setWpsFileToken(activationSn);
        }
        sdkReady = true;
        resolve();
      },
    });
  });
}

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

页面打开按钮应在 isWpsReady() 为 false 时禁用，并展示「文档能力初始化中」，避免静默失败后弹泛化错误。换 HAR 后务必 clean 再编译，确认 import 均来自 @wps/wps_sdk。

四、打开侧如何消费就绪态

注册成功只表示有权调用 SDK，不表示文档已经打开。打开仍走 OpenFileRequest + sendRequest。未就绪时不要用 try/catch 把「未注册异常」和「打开非 OK」揉成同一条 Toast。

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

export async function openReadonly(
  ctx: common.UIAbilityContext,
  sandboxPath: string
): Promise<Result> {
  if (!isWpsReady()) {
    await bootstrapWps(APP_KEY, APP_SECRET, MAYBE_SN);
  }
  const req = new OpenFileRequest(ctx, sandboxPath);
  return WPSApi.sendRequest(req);
}

export async function handleOpen(ctx: common.UIAbilityContext, path: string): Promise<void> {
  try {
    const r = await openReadonly(ctx, path);
    if (r.code !== ResultCode.OK) {
      console.error('[WPS] open non-ok', r.code, r.msg);
      return;
    }
    console.info('[WPS] open ok');
  } catch (e) {
    console.error('[WPS] open exception', e);
  }
}

路径建议先拷贝到应用沙箱再传入。注册失败时不要继续叠加 enableEdit 或水印字段做对照实验，先把 code/msg 打全。

五、1013 与包名归档

1013 出现时，优先暂停打开参数实验。把运行时打印的 bundleName、申请凭据时填写的包名、当前 HAR 文件名三列并排对照。调试包与正式包包名不同时，必须分开归档，否则会出现「调试正常、正式包反复 1013」却被当成偶现打不开。

联调日志建议统一前缀 [WPS]，固定记录：注册 code/msg、是否已设 Token、打开前后路径、打开 code/msg 或异常栈。设备侧过滤关键字：registerApp、1013、open non-ok、open exception。

记录项	填写
HAR 文件名
运行时 Bundle
申请包名
注册结果	OK / code:msg
Token	已设 / 无需
只读打开	通过 / 失败

六、联调顺序与常见误用

推荐顺序：冷启动注册 OK → 沙箱路径只读打开 → 再开 enableEdit。不要在注册回调未到之前并行发起多个 sendRequest。不要在多个页面各自调用 registerApp，以免就绪标志不一致。全仓搜索 request.wpsToken 旧写法并清理，激活序列号应收回全局设置。

Ability 启动注册、页面消费就绪态这一结构，建议在评审纪要里写明负责人与文件路径，避免下一位同事再次把 registerApp 写回某个按钮点击回调。HAR 批次变更时，CHANGELOG 写清文件名与回归项：注册 OK、只读打开。远程协助时一次带齐 Bundle、HAR 交付日、注册 code/msg，通常能少问两轮。

七、小结

WPS Open SDK 鸿蒙版的打开能力建立在注册门禁之上：registerApp 到 ResultCode.OK 之前，sendRequest 不应被调用。工程上把 bootstrap 与打开 helper 拆开，用 sdkReady 连接页面，用 1013 与「未注册异常」做分流，联调会从猜原因变成对表排查。字段与错误码以官方对接文档为准，随 SDK 批次核对后再合入。

依赖写法示例：

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

执行 ohpm install 后全量编译。把对接文档入口写进 README，每次 HAR 变更后重跑注册与只读打开。

---

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