在 HarmonyOS 工程里，早期接入的 WPS Open SDK 往往已经能打开文档，但依赖包、注册时机、激活序列号挂载位置与打开参数写法可能仍停留在旧交付约定。统一接口交付后，对外入口仍是单例 WPSApi，调用链也仍是 registerApp →（按需）setWpsFileToken → OpenFileRequest + sendRequest，迁移工作的重点不是重学一套 API，而是把工程里散落的旧假设对齐到同一套参数与门禁。本文按「迁移动机 → 依赖替换 → 注册与 Token → 打开链路改造 → 验收清单」整理可直接落地的联调说明，字段语义以官方对接文档为准。

一、迁移在接入链路中的位置

建议把迁移拆成四层，避免只换 HAR 却不改调用顺序：

1. 交付层：用新批次 wps_sdk.har 替换 libs/，更新 oh-package.json5 后执行 ohpm install。
2. 身份层：确认运行时 bundleName 与申请归档一致，appKey / appSecret 与当前 HAR 同源。
3. 注册层：启动阶段观察 ResultCode.OK，业务打开入口绑定「就绪态」，禁止未注册成功就 sendRequest。
4. 参数层：激活序列号改走 setWpsFileToken；打开侧只保留 enableEdit、回传、水印等业务参数。

层级	旧工程常见写法	统一接口目标态
依赖	多份 HAR / 路径漂移	单一 file:./libs/wps_sdk.har
Token	写在 OpenFileRequest 临时字段	注册成功回调里全局设置
打开	注册与打开耦合在同一按钮	就绪标志门禁后再打开
排错	只看「打不开」	分流 code/msg 与异常栈

官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT 。迁移评审建议把该链接与 HAR 批次号一并写入变更说明。

二、依赖与凭据先对齐，再改业务代码

迁移失败里很大一部分其实是「新 HAR + 旧凭据」或「调试包名与申请包名不一致」。建议按固定顺序处理：

1. 备份旧 libs/wps_sdk.har 与 oh-package.json5 依赖段。
2. 放入新交付 HAR，依赖写法保持：

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

3. 执行 ohpm install，清理旧编译缓存后全量编译。
4. 启动时打印 Bundle，与申请材料逐字核对。
5. 若包名变更，必须重新申请凭据，不能只改本地字符串。

凭据在 SDK 侧为本地校验；应用侧要保证 appKey / appSecret 完整、未截断、未混入空白。限时凭据过期时，按官方渠道续期后再联调，不要用「多试几次」掩盖身份问题。1013（ERROR_CODE_AUTH_FAILURE）在迁移窗口尤其常见，优先核对 HAR 批次与 Bundle，再怀疑业务参数。

三、注册门禁与 Token 全局化

旧代码常见两类写法需要改掉：一是打开前未确认注册成功；二是每次构造 OpenFileRequest 时塞 Token。统一接口推荐：注册成功后再打开；需要序列号时在回调里调用 setWpsFileToken，让后续打开请求自动携带。

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

type ReadyState = 'idle' | 'registering' | 'ready' | 'failed';

let state: ReadyState = 'idle';
let lastError = '';

export function migrateBootstrap(
  appKey: string,
  appSecret: string,
  fileToken?: string
): void {
  if (!appKey || !appSecret) {
    state = 'failed';
    lastError = 'empty credentials';
    return;
  }
  state = 'registering';
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (result: Result): void => {
      if (result.code !== ResultCode.OK) {
        state = 'failed';
        lastError = `${result.code}:${result.msg}`;
        console.error('registerApp', lastError);
        return;
      }
      // 需要序列号的交付形态：注册成功后全局设置，勿写到 Request
      if (fileToken) {
        WPSApi.setWpsFileToken(fileToken);
      }
      state = 'ready';
    },
  });
}

export function canOpenAfterMigration(): boolean {
  return state === 'ready';
}

export async function openAfterMigration(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  needEdit: boolean
): Promise<void> {
  if (state !== 'ready') {
    throw new Error(`sdk not ready: ${state} ${lastError}`);
  }
  const request = new OpenFileRequest(ctx, sandboxPath);
  if (needEdit) {
    request.enableEdit = true;
  }
  // 不要再设置 request.wpsToken
  try {
    const result = await WPSApi.sendRequest(request);
    if (result.code !== ResultCode.OK) {
      console.error('sendRequest', result.code, result.msg);
    }
  } catch (e) {
    // 未注册成功时常见：Promise 抛异常
    console.error('sendRequest exception', e);
  }
}

说明：fileToken 用可选参数表达「有则设置、无则跳过」，避免在业务层散落版本分支。打开按钮、菜单项应绑定 canOpenAfterMigration()，防止用户在注册回调返回前点击导致异常。enableEdit 不传或为 false 均为只读，迁移验收若要求可编辑，必须显式赋 true。

四、打开链路与回传改造要点

迁移到统一接口后，打开侧仍建议坚持：

• 路径先入沙箱：系统选择器路径拷贝到本应用可访问目录，再传给 OpenFileRequest。
• 参数只保留业务意图：编辑、水印、extraOptions、关闭回传等按产品验收配置。
• 结果三分流：ResultCode.OK、非 OK 的 code/msg、以及未注册导致的异常，分别打日志。
• 回传要落盘：若开启关闭回传，fileUri / FD 属于 WPS 侧临时结果，须拷贝到本应用沙箱后再入库或上传。

检查项	迁移前症状	迁移后判定
注册门禁	偶发打开异常	就绪态为真才允许打开
Token 位置	每次打开重复赋值	仅注册回调设置一次
编辑验收	「不能改」	确认 enableEdit = true
回传路径	业务拿不到文件	完成沙箱拷贝后再用

旧工程若把水印、回传、功能开关与注册写在同一巨型函数里，迁移时建议拆成「bootstrap」与「open」两个模块，降低回归成本。HAR 升级后若个别参数行为与旧批次不一致，以当前对接文档参数表为准做对照，不要沿用口头约定。

五、迁移验收清单（可贴进评审）

发布前至少完成下列核对，并保留日志截图：

1. ohpm install 后工程依赖指向新 HAR，编译无旧符号残留。
2. 运行时 Bundle 与申请归档一致；凭据非空且未混用历史批次。
3. 冷启动观察到 registerApp → ResultCode.OK；失败时记录 code/msg。
4. 需要序列号时已调用 setWpsFileToken；代码检索不到对 request.wpsToken 的赋值。
5. 未就绪时点击打开会提示或禁用，不会直接抛到用户可见崩溃。
6. 只读 / 可编辑各验一次；可编辑场景确认已设 enableEdit = true。
7. 若启用回传：关窗后业务侧拿到沙箱内最终路径，而非临时 URI。
8. 错误码 1013、参数不完整、未注册异常均有独立日志关键字，便于远程协助。

联调现场建议准备一份「迁移前后对照」：旧 HAR 文件名、新 HAR 文件名、Bundle、注册结果、打开结果。材料齐全时，对照文档章节比反复猜测更快。

六、常见回归与处理顺序

迁移窗口高频问题可按下面顺序排查：

编译或导入失败
先确认 HAR 路径与 ohpm install；再核对 import 是否仍使用 @wps/wps_sdk 公开类型（WPSApi、OpenFileRequest、ResultCode）。

注册失败
空凭据、包名不一致、凭据过期分别对应不同处理；不要先改打开参数。

能注册不能打开
检查是否在回调成功前调用了 sendRequest；检查沙箱路径是否可读。

能打开不能编辑
回到 enableEdit，不要误判为鉴权问题。

关窗无业务文件
核对回传开关与拷贝逻辑，而不是重复注册。

七、小结

把旧版 WPS Open SDK 迁到统一接口，核心是对齐交付、身份、注册门禁与 Token 挂载位置，而不是重写整套业务页面。工程上用「可选 fileToken + 就绪态」即可覆盖多数交付形态；打开侧保持沙箱路径与参数显式化，回传侧完成落盘，验收就能稳定复现。建议将本文清单固化进发布评审模板，并在仓库内固定对接文档链接，后续 HAR 再升级时按同一路径增量核对即可。

---

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