在 HarmonyOS 工程里接入wps/wps_sdk时验收标准往往不是「能编译」而是「冷启动注册成功、沙箱内路径能拉起 WPS、日志能区分未注册与打开失败」。本文按官方对接文档的接入全流程把 HAR 落盘、依赖声明、RegisterAppRequest注册、OpenFileRequest打开与Result归因写成一条可复制的最小路径便于首轮联调与 Code Review。一、工程侧HAR 与 ohpm 依赖SDK 以 HAR 形式交付包名wps/wps_sdk。典型做法是将厂商提供的wps_sdk.har放入工程libs/在oh-package.json5中声明 file 依赖再执行ohpm install拉齐依赖图。集成完成后业务模块即可import { WPSApi, RegisterAppRequest, OpenFileRequest, ResultCode } from wps/wps_sdk。步骤操作验收落盘libs/wps_sdk.har文件与申请版本一致声明oh-package.json5→ dependenciesohpm install无报错编译引用wps/wps_sdkHAP 能链接 HAR凭据appKey / appSecret与 HAR 需与申请时绑定的bundleName一致换包名或换交付包后须重新申请否则注册阶段常出现鉴权失败类错误码。多 flavor 交付时不要把调试包的 key 打进 release 变体在构建脚本中按 product 注入常量并在 CI 中增加「包名—凭据」对照表检查避免测试环境正常、上架包 1013 的割裂现象。模块侧只需保证entry依赖了含 HAR 的 feature不必在 UI 层散落import路径。若团队使用远程 HAR 仓库仍建议在版本说明中锁定文件名与申请邮件编号方便审计与回滚。二、注册链RegisterAppRequest 与 wpsReady 门闩对接文档要求在registerApp/RegisterAppRequest成功之前其它WPSApi.sendRequest可能 reject 或不可用。工程上应把注册收敛为单次ensureRegistered用布尔门闩避免重复注册与并发双调。import{common}fromkit.AbilityKit;import{WPSApi,RegisterAppRequest,OpenFileRequest,ResultCode,}fromwps/wps_sdk;letwpsReadyfalse;exportasyncfunctionensureRegistered(ctx:common.UIAbilityContext):Promisevoid{if(wpsReady)return;constrawaitWPSApi.sendRequest(newRegisterAppRequest(ctx,APP_KEY,APP_SECRET));if(r.codeResultCode.ERROR_CODE_AUTH_FAILURE){thrownewError(auth failed:${r.msg??});}if(r.code!ResultCode.OK){thrownewError(register${r.code}${r.msg??});}wpsReadytrue;}建议在UIAbility冷启动路径await ensureRegistered一次所有「打开文档」按钮在wpsReady为真前禁用。Release 构建禁止打印完整 secret日志仅保留code/msg与bundleName核对结果。若签发凭据要求在注册成功后注入激活序列号应在ResultCode.OK分支调用WPSApi.setWpsFileToken且优先全局设置避免在每次OpenFileRequest上重复赋值导致行为漂移。三、打开链沙箱路径与 enableEdit 默认值OpenFileRequest构造需要UIAbilityContext与可读filePath。从系统文档选择器拿到的 URI 往往不在应用沙箱内直接传入容易在sendRequest回调中得到ResultCode.ERROR。推荐先copyFileSync到filesDir再传沙箱绝对路径。exportasyncfunctionopenDocReadOnly(ctx:common.UIAbilityContext,sandboxPath:string):Promisevoid{awaitensureRegistered(ctx);constreqnewOpenFileRequest(ctx,sandboxPath);req.enableEditfalse;constrawaitWPSApi.sendRequest(req);if(r.code!ResultCode.OK){thrownewError(open${r.code}${r.msg??});}}enableEdit未赋值或为false时语义为只读这是能力默认值而非缺陷。预览入口与编辑入口应共用同一函数仅布尔参数不同避免仓库内出现多份new OpenFileRequest拷贝。四、Promise 与异常未注册 vs 打开失败sendRequest返回PromiseResult。未注册成功时可能进入.catch这与result.code ! OK的打开失败是两类问题日志与监控应分维度统计。现象优先检查Promise reject是否已ensureRegistered是否并发在注册完成前点击ERROR_CODE_AUTH_FAILUREappKey/secret、HAR 与包名是否与申请一致ResultCode.ERROR打开沙箱路径是否存在、是否可读OK且无data未开启关窗回传时为正常勿误判上传失败联调清单建议打印固定前缀日志例如stageregister|open与code便于 grep 导出。五、选择器路径拷贝示例下列片段演示「选择器 URI → 沙箱文件 → 打开」的最小路径便于与仅传 URI 的失败案例对照。实际项目请按业务封装为copyIntoSandbox工具函数并处理大文件异步拷贝与进度提示。import{fileIo}fromkit.CoreFileKit;functioncopyIntoSandbox(srcUri:string,destPath:string):void{constsrcfileIo.openSync(srcUri,fileIo.OpenMode.READ_ONLY);constdestfileIo.openSync(destPath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY);fileIo.copyFileSync(src.fd,dest.fd);fileIo.closeSync(src);fileIo.closeSync(dest);}拷贝完成后再调用openDocReadOnly(ctx, destPath)。若跳过拷贝日志里往往只有笼统的ERROR排查会浪费大量时间。六、UIAbility 与生命周期配合文档打开通常发生在用户点击之后此时UIAbilityContext必须仍有效。若从后台恢复后 context 变化应使用当前 Ability 的 context 构造OpenFileRequest不要缓存已销毁的 context。冷启动注册与「首屏可点」之间建议加短 loading注册失败时展示msg避免用户连点触发多次sendRequest。Ability 被系统回收后再次进入应确认wpsReady是否仍需重置若进程被杀静态变量会丢失需要重新ensureRegistered不要把「上次注册过」当成跨进程持久状态。七、小结与首轮联调顺序建议按序推进HAR 编译通过 → 仅ensureRegistered断言OK→ 沙箱内只读打开 → 再开enableEdit→ 最后叠策略字段。每步保留日志样例回归时对比code是否突变。正式签名包与调试包若包名不同须使用各自邮件签发的凭据混用会在上架阶段集中暴露为鉴权失败。HarmonyOS WPS Open SDK 的快速入门本质是「HAR 正确集成 注册门闩 沙箱路径 分清 reject 与 Result」。把ensureRegistered与openDoc收进基础库页面只调 Facade比在每个 Activity 抄 Demo 更易维护。字段语义与错误码表以官方对接文档为准实现侧保持单点sendRequest出口联调成本会明显下降。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT