HarmonyOS WPS Open SDK 实践：从 HAR 集成到 OpenFileRequest 最小闭环

集成 @wps/wps_sdk 后，团队常见两个误判：把 sendRequest 的 Promise reject 当成「WPS 打不开」，以及把 enableEdit 默认值当成缺陷。本文基于官方对接文档，把 HAR 集成、WPSApi.sendRequest 注册链、沙箱路径打开与 ResultCode 归因写成可落地的 Facade 模板，并给出联调时建议打印的字段，方便在掘金侧做技术复盘。全文假设读者已能创建 HarmonyOS Stage 模型工程，并熟悉 UIAbility 与 ohpm 基本命令，不展开 ArkUI 布局细节。

一、依赖图：HAR 与入口类

SDK 以 HAR 交付，ohpm 声明 file 依赖后，业务代码统一从 @wps/wps_sdk 引入 WPSApi、RegisterAppRequest、OpenFileRequest、ResultCode。对外只暴露 Facade，避免页面层直接 new RegisterAppRequest，否则后续换注册时序时改动面过大。

集成验收不要只看 IDE 不报错：用一台未装 WPS 的模拟器与真机各跑一遍注册与打开，确认拉起行为符合预期。oh-package.json5 中 file 依赖路径错误时，有时要到链接阶段才暴露；建议在 README 中记录当前锁定的 HAR 文件名与 checksum，避免同事误换旧包。

多模块工程里，把 WPS Facade 放在独立 feature 或 common 库，由 entry 依赖，UI 模块只依赖 Facade 接口。这样可以把 APP_KEY 通过构建变体注入，而不是硬编码在页面组件中。

二、注册：单次 ensureRegistered

typescript 复制代码

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

let wpsReady = false;

export async function ensureRegistered(
  ctx: common.UIAbilityContext
): Promise<void> {
  if (wpsReady) return;
  const r = await WPSApi.sendRequest(
    new RegisterAppRequest(ctx, APP_KEY, APP_SECRET)
  );
  if (r.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
    throw new Error(`auth: ${r.msg}`);
  }
  if (r.code !== ResultCode.OK) {
    throw new Error(`register ${r.code}`);
  }
  wpsReady = true;
}

冷启动在 UIAbility 生命周期内 await ensureRegistered；用户触发打开前若 !wpsReady，按钮保持禁用。凭据与 bundleName 绑定，换包须重新申请 key。若邮件签发的凭据要求在注册成功后设置激活序列号，在 ResultCode.OK 分支调用 WPSApi.setWpsFileToken，并写在 Facade 注释里标明文档章节，避免半年后无人记得注入条件。

进程被系统杀死后，wpsReady 静态变量会重置，不能假设「本次进程已注册」可以跨 Ability 实例复用错误逻辑。每次新进程仍要走一遍注册，但门闩可以防止同进程内重复 RegisterAppRequest。

三、打开：沙箱路径与只读默认

typescript 复制代码

export async function openDoc(
  ctx: common.UIAbilityContext,
  path: string,
  editable: boolean
): Promise<void> {
  await ensureRegistered(ctx);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = editable;
  const r = await WPSApi.sendRequest(req);
  if (r.code !== ResultCode.OK) {
    throw new Error(`open ${r.code} ${r.msg ?? ''}`);
  }
}

选择器 URI 应先拷贝到 filesDir。OK 且无 data 在未开回传时合法，勿当上传失败。拷贝大文件时建议在 UI 上展示「准备中」，防止用户连点触发并发 sendRequest；Facade 内可用简单互斥锁或 opening 标志位挡连点。

预览与编辑应共用 openDoc(ctx, path, editable)，禁止复制第二份 OpenFileRequest 构造逻辑。评审规则：任何新增字段必须附带文档语义注释，例如 // open-params enableEdit。

四、reject 与 Result 的分账

类型	含义	动作
`.catch`	多未注册	查 `ensureRegistered` 时序
`ERROR_CODE_AUTH_FAILURE`	凭据/包名	对照申请单
打开 `ERROR`	路径/权限	查沙箱与 `enableEdit`

建议封装 logWps(stage, code, msg)，禁止打印 secret。监控侧可为 register_fail、open_fail 分别计数，维度带 code，上线后若某 code 突增，回查对应文档段落是否近期变更。

集成测试至少三条：注册失败（故意错 key）、只读打开、编辑打开。每条断言 Result.code，并把日志样例存进 Wiki 作为回归基线。

五、扩展顺序与工程习惯

先只读打开跑绿，再 editable=true，最后才加水印与 extraOptions。每层能力单独提交，Code Review 只审新增字段是否文档允许。换 HAR 后执行 clean 重装，避免旧 so 导致错误码随机；与后端联调时，约定「最小可打开附件」作为每日冒烟用例。

Ability 从后台回到前台时，确认 context 仍有效；不要在全局单例里缓存已销毁的 UIAbilityContext。若业务需要在多个 Ability 间打开文档，每个 Ability 使用自己的 context 调 Facade，共享的仅是 wpsReady 与凭据常量。

拷贝选择器文件时，可抽 copyIntoSandbox 工具函数，失败时向上抛出并带 errno 或路径信息，避免与 WPS 打开错误混淆。临时文件生命周期要与编辑会话对齐：关窗后再删沙箱副本，防止 WPS 仍持有句柄。

Code Review 检查清单：new OpenFileRequest 是否只出现在 Facade；注册是否只在 ensureRegistered；页面是否无硬编码 key；日志是否无 secret；enableEdit 是否在预览入口显式为 false。上线前用正式签名包跑一遍注册与打开，避免调试包凭据与上架包名不一致。

六、小结

快速入门的关键是注册门闩 + 沙箱路径 + 日志分 stage。Facade 固定 sendRequest 出口，页面不堆参数，后续迭代会轻松很多。官方对接文档描述的是能力边界与推荐时序，实现时以当前 HAR 行为为准；当代码与文档冲突时，先记录现象与 code，再向技术支持确认文档 revision。把本文的 ensureRegistered / openDoc 模板落库后，新人 onboarding 可按「编译 → 注册 OK → 沙箱只读」三天节奏推进，比一次性阅读全文档更高效。仓库内可维护 docs/wps-smoke-log.txt 记录每次 HAR 升级后的冒烟结果，包含注册耗时、打开耗时与样例 code，方便对比性能回退。若使用依赖注入框架，将 Facade 注册为单例即可，不要把 UIAbilityContext 存进单例字段。联调周报可固定记录「注册 OK 率」「打开 OK 率」与 Top3 code，便于版本对比与 HAR 升级决策。

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。

官方对接文档：365.kdocs.cn/l/clQl5cek2...

技术交流 QQ 群：628436767