HarmonyOS WPS Open SDK 实践：旧版工程怎么迁到统一版

团队里如果已经有一版能跑的鸿蒙 WPS 二开接入，面对「统一版」时最常见的疑问不是「API 叫什么」，而是：旧 HAR 能不能直接替换？专业版（ToB）与个人版（ToC）是不是两套代码？激活序列号还要不要每次塞进 OpenFileRequest？本文按真实迁移顺序写：先对齐交付与包名，再收口注册与 Token，最后用 SdkConstants.isPersonalSdk() 做轻量分支，让一套业务代码同时服务双版本交付。

统一版到底统一了什么

统一版的关键变化可以概括成三句话：

1. 接口统一：入口仍是 WPSApi，打开仍用 OpenFileRequest + sendRequest。
2. 流程统一：两端都必须 registerApp 成功后才能打开。
3. 差异显式化：ToB 通常要在注册成功回调里 setWpsFileToken；ToC 注册成功即可打开，无需 Token；部分能力（如文档不落地）仅在对应交付上生效。

对比项	迁移时怎么处理
HAR / 凭据	按目标客户端版本重新申请，不可混用
API 表面	尽量少改业务调用，多改初始化
Token	从 Request 临时字段迁到全局 setWpsFileToken
能力开关	以对接文档「是否生效」列为准

以往痛点往往是「只能覆盖某一类客户端」或「两套文档两套习惯」。统一版把开发体验拉齐后，迁移成本主要花在工程卫生上，而不是重写 UI。

迁移步骤：依赖 → 身份 → 初始化

1）替换 HAR 与依赖

把新交付的 wps_sdk.har 放进 libs/，oh-package.json5 使用本地 file 依赖，然后 ohpm install。迁移窗口务必保留旧包备份，方便 A/B 对照注册结果。

2）核对 Bundle 与凭据

appKey / appSecret 与包名绑定。调试包与正式包 Bundle 不同时，要分别申请或明确以哪套为准。遇到 1013（ERROR_CODE_AUTH_FAILURE），先查身份，再查业务参数。

3）重写 bootstrap，而不是重写打开页

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

let ready = false;

export function bootstrapUnified(
  appKey: string,
  appSecret: string,
  proSn?: string
): void {
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (result: Result): void => {
      if (result.code !== ResultCode.OK) {
        ready = false;
        console.error('registerApp failed', result.code, result.msg);
        return;
      }
      // ToB：注册成功后设置激活序列号；ToC：跳过
      if (!SdkConstants.isPersonalSdk() && proSn) {
        WPSApi.setWpsFileToken(proSn);
      }
      ready = true;
    },
  });
}

export async function openUnified(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  editable: boolean
): Promise<void> {
  if (!ready) {
    throw new Error('call sendRequest only after registerApp OK');
  }
  const request = new OpenFileRequest(ctx, sandboxPath);
  request.enableEdit = editable;
  // 不推荐再写 request.wpsToken
  const result = await WPSApi.sendRequest(request);
  if (result.code !== ResultCode.OK) {
    console.error('open failed', result.code, result.msg);
  }
}

这段代码的迁移含义：

• 同一套打开逻辑服务 ToB / ToC。
• 版本差异收口在注册回调，而不是散落在每个业务按钮。
• Token 全局化后，打开页不再关心序列号来源。

参数与能力：哪些要重测

统一版 API 一致，不代表所有参数在两端行为相同。迁移回归建议按「必测 / 选测」分层：

必测

• 冷启动注册成功；未就绪打开被拦截。
• 沙箱路径打开成功；系统选择器路径先拷贝再打开。
• enableEdit 默认只读 vs 显式可编辑。
• 关闭回传开启时，业务侧完成 URI/FD 落盘。

按交付选测

• ToB：setWpsFileToken 后打开；不落地相关能力按文档验证。
• ToC：确认未误调 Token；确认部分高级参数「设置不生效」符合预期。
• extraOptions、水印、修订：对照参数表「是否生效」列，避免把「不生效」当成 Bug。

场景	旧工程习惯	统一版建议
Token	每次 Request 赋值	注册回调全局设置
版本判断	猜 WPS 包名	SdkConstants.isPersonalSdk()
排错	口头描述打不开	固定上报 Bundle、HAR、code/msg

迁移清单（可直接贴进 PR）

1. 新 HAR 已安装；旧 HAR 已归档标注停用日期。
2. 邮件/申请单上的版本（ToB 或 ToC）与工程依赖一致。
3. 运行时 Bundle 与申请包名一致。
4. registerApp 成功日志可检索；失败保留 code/msg。
5. ToB 路径存在 setWpsFileToken；ToC 路径不强制 Token。
6. 全仓搜索 wpsToken，确认没有残留在 Request 上的旧写法。
7. 打开入口绑定 ready；异常与非 OK 分流。
8. 编辑、回传、水印按产品验收各跑通一次。
9. 文档链接写入 README：365.kdocs.cn/l/clQl5cek2…

联调时怎么提问更高效

迁移问题若要邮件或社群协助，建议一次带齐：

1. 目标版本（ToB / ToC）与 HAR 交付日
2. 运行时 Bundle
3. registerApp 的 code / msg
4. sendRequest 结果或异常栈
5. 是否已调用 setWpsFileToken（ToB）
6. 已对照文档的哪一节仍无法解释

技术支持邮箱：m_open_sdk@wps.cn。材料越完整，越少来回确认「是不是混用了凭据」。

排障顺序与工程结构

建议按「能不能注册 → 能不能打开 → 打开后行为对不对」三段处理，避免在注册失败时先改水印或 extraOptions。注册段重点看空凭据、包名不一致、凭据过期、HAR 与申请版本混用，日志固定打印 code/msg 并附 Bundle 与 HAR 文件名。打开段若 sendRequest 抛异常优先怀疑未就绪；返回非 OK 再查沙箱路径与客户端版本。行为段：「不能编辑」查 enableEdit，「关窗无文件」查回传拷贝，「开关无效」先查文档是否对该交付生效。

工程上建议收拢为 WpsBootstrap.ets（registerApp / Token / 就绪态）与 WpsOpenHelper.ets（OpenFileRequest / Result）。业务页只依赖「是否就绪」和「打开某路径」。凭据走本地安全配置或构建注入；HAR 文件名、交付日、ToB/ToC 写进 docs/wps-sdk.md。若历史工程把注册写在页面 aboutToAppear，应上移到 Ability 启动阶段，页面只消费就绪态，不重复 registerApp。

小结

从旧版迁到 WPS Open SDK 鸿蒙统一版，本质是一次「交付对齐 + 初始化收口」：HAR 与凭据同源、注册门禁清晰、Token 全局化、打开参数按文档重测。业务页尽量复用，把版本差异留在 bootstrap。做完上述清单后，后续无论扩展 ToC 覆盖还是保持 ToB 安全能力，都可以在同一套代码骨架上演进。

---

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