HarmonyOS WPS Open SDK 实践：registerApp 鉴权与就绪门禁

HarmonyOS 生态里，行业应用要在端内打开 Office 文档，WPS Open SDK 是常见选型。统一版把专业版（ToB）与个人版（ToC）收成同一套 WPSApi，但对开发侧仍有一条不可跳过的纪律：registerApp 回调未到 ResultCode.OK 之前调用 sendRequest 会抛异常。这不是打开失败，而是链路未就绪。本文从架构角度把注册收成独立门禁：启动时注册、成功后再按形态注入 Token、页面只消费 sdkReady，联调时用 1013 与未注册异常做分层归因。

为什么注册必须独立成层

以往痛点是：打开页复制粘贴三份 registerApp，有的写在按钮点击里，有的写在 aboutToAppear，调试包碰巧成功，正式包却反复 1013。统一版并没有取消注册，只是把对外模型固定为：

rust 复制代码

HAR → registerApp → (ToB) setWpsFileToken → OpenFileRequest → sendRequest → Result

形态	registerApp	setWpsFileToken
ToB（专业版）	必须	注册成功回调中设置
ToC（个人版）	必须	不需要

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

官方调用与 Result 分流

入口签名是 WPSApi.registerApp(appKey, appSecret, callback)。校验在本地完成，不依赖联网。appKey / appSecret 与申请时的包名绑定；调试包与商店包包名不同，必须分开申请。

typescript 复制代码

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('[WPS] register', r.code, r.msg);
        return;
      }
      if (!SdkConstants.isPersonalSdk() && proSn) {
        WPSApi.setWpsFileToken(proSn);
      }
      sdkReady = true;
    },
  });
}

Release 禁止打印完整 appSecret。1013（ERROR_CODE_AUTH_FAILURE）出现时暂停参数实验，先对齐 Bundle、凭据与 HAR。ResultCode.ERROR 更常见于 key/secret 为空。未注册就 sendRequest，走的是 Promise reject，不要和打开非 OK 共用一条 UI 文案。

页面只依赖就绪标志

Ability 启动阶段发起注册，避免用户点击「打开」时才首次注册导致首屏等待与竞态。若产品要求离线下也能看到按钮，可用 sdkReady === false 时禁用并展示「文档能力初始化中」。

typescript 复制代码

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

export async function openAfterReady(
  ctx: common.UIAbilityContext,
  path: string
): Promise<Result> {
  if (!sdkReady) {
    throw new Error('WPS not registered');
  }
  const req = new OpenFileRequest(ctx, path);
  return WPSApi.sendRequest(req);
}

工程结构上推荐两文件分工：WpsBootstrap.ts 只做注册与就绪标志；WpsOpenHelper.ts 负责沙箱拷贝、构造 Request、处理 Promise。统一版升级时通常只需回归这两处，而不是全仓搜 registerApp 散落点。

联调地图：从 1013 到打开

错误分流顺序：HAR/Bundle → 注册 → 打开参数。1013 时把 Bundle 打印值与申请归档并排对照；注册 OK 后再验证只读打开。ToB 确认 setWpsFileToken 已在成功回调执行；ToC 确认没有多余的 SN 注入。

步骤	通过标准
冷启动注册	日志见 `ResultCode.OK`
Token（ToB）	成功回调中已设
Token（ToC）	未调用 `setWpsFileToken`
只读打开	WPS 拉起，无未注册异常
正式包包名	无 `1013`

设备侧过滤：registerApp、1013、open exception。远程协助一次带齐 HAR 文件名、Bundle、注册 code/msg、是否已设 Token。发版评审建议把这四列贴进检查表，比临发口头确认更稳。

依赖、日志与协作

统一版仍以 HAR 交付。执行 ohpm install 后全量编译，确认业务代码 import 均来自 @wps/wps_sdk，而不是历史相对路径拷贝。HAR 批次变更时，在 CHANGELOG 写清文件名与回归项：注册 OK、只读打开、（若启用）可编辑。Ability 启动阶段发起注册，避免点击路径上的竞态；若产品要求离线下也能看到「打开」按钮，用 sdkReady === false 禁用并展示初始化文案。

联调阶段统一日志前缀 [WPS]，固定记录 register 的 code/msg、是否已设 Token、打开前后路径与结果。设备侧过滤 registerApp、1013、open non-ok、open exception。回传开启时在 resolve 分支记录 data 是否存在，并在拷贝完成后记录目标路径。调试包与正式包包名不同时，申请材料必须分开归档，否则 1013 会反复出现却被当成偶现打不开。

对团队而言，统一版还带来：参数表与错误码单一来源、预览/编辑/审批共用 WpsOpenHelper、ToB/ToC 各一套必测矩阵。发版评审建议附上 HAR 文件名、Bundle 打印值、一次注册 OK 与一次成功打开日志，远程协助时可少问两轮。多人协作时约定：新需求只允许扩展 Facade，不允许平行 Helper。

实践建议

不要在多个页面分叉注册。出现打开异常时，先区分「未注册」与「打开非 OK」：前者修门禁，后者查路径与客户端。HAR 批次变更后，先只替换依赖并重跑注册与只读打开，确认身份无回归再恢复高级参数。水印、extraOptions、不落地应在同一打开封装内按验收追加，不要在多个页面分叉配置。

注册层建议沉淀 ensureWpsRegistered，业务页面只关心三种用户态：「文档已打开」「回传文件已就绪」「可重试的失败」。上传模块订阅回传成功事件，而不是在打开按钮回调里假设 data 一定有值。对交付物还会把 code/msg 写入本地诊断日志，方便驻场同事导出排查。建议将注册、打开、回传三条链路的错误码用例写入手工测试表，每次升级 HAR 或 WPS 客户端后回归一遍。

若本周只完成注册与只读打开，下周再按可编辑 → 策略字段 → 回传递增，每层保留成功与失败日志各一份。把对接文档入口写进 README 与内部 Wiki，避免每人收藏不同版本的链接副本。HarmonyOS WPS Open SDK 把「文档二开」收敛成一条可重复的调用链，但链头仍是 registerApp。守住启动注册、Token 全局化、1013 先于参数实验这三条纪律，打开侧的联调时间会明显下降。对接文档：365.kdocs.cn/l/clQl5cek2... ；技术支持：m_open_sdk@wps.cn；技术交流 QQ 群：628436767。

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