在 HarmonyOS 业务应用里接入 @wps/wps_sdk，对外统一入口是单例 WPSApi。无论打开文档还是完成注册，最终都落到「构造 Request → sendRequest → 处理 Result」这条链上。弄清这个范式，比零散堆字段更重要：未注册就打开会进 catch，开了回传要等关窗，code/msg/data 各司其职。本文按调用链说明，字段语义以官方对接文档为准。把调用面收稳之后，再叠编辑、回传或策略字段会轻松很多，联调也更好归因。

一、WPSApi 在接入中的位置

推荐时序：注册成功 →（按凭据约定设置全局 Token）→ 文件入本应用沙箱 → 构造 OpenFileRequest → sendRequest → 按 Result 分支。

sendRequest 当前主要承载打开文档（RequestType.OPEN_FILE）。页面层不要各自 new 一套调用，差异收在 Facade，便于 Code Review 与复测。一次堆满所有开关时，ResultCode.ERROR 很难归因；联调应先绿「注册 + 可打开」，再谈编辑与回传。

二、注册：sendRequest 的门禁

对接文档写明：必须在 sendRequest 之前注册成功。未注册完成就发起请求会 抛异常，须 .catch() 或 try/catch。appKey / appSecret 与包名绑定，调试包与正式包须分别申请，否则常见 1013。

let wpsReady = false;

async function ensureRegistered(ctx: 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(`1013: ${r.msg ?? ''}`);
  }
  if (r.code !== ResultCode.OK) {
    throw new Error(`register ${r.code}`);
  }
  wpsReady = true;
}

也可用回调式 WPSApi.registerApp(appKey, appSecret, { onCallback })；无论哪种，就绪标记要在业务打开前成立。打开按钮在注册完成前禁用。日志区分「注册失败」与「打开失败」。换 HAR 后 clean；Release 不打印 secret。

若申请材料含激活序列号，对接文档推荐在注册 ResultCode.OK 后调用 WPSApi.setWpsFileToken，全局生效；不要每次打开再写 wpsToken。同一工程多渠道包时，凭据按包名分目录存放，避免调试包密钥误入正式包。限时凭据失效需重新申请，不要在业务层用「再试一次」掩盖鉴权问题。

三、sendRequest：Promise 与 Result

async function openLocalDoc(
  ctx: UIAbilityContext,
  sandboxPath: string,
  editable: boolean
): Promise<Result> {
  await ensureRegistered(ctx);
  const req = new OpenFileRequest(ctx, sandboxPath);
  req.enableEdit = editable;
  return WPSApi.sendRequest(req);
}

处理约定：1）.then / await 看 code === ResultCode.OK；2）.catch 捕获「尚未注册」等异常；3）未开回传时 OK 且 data 空属正常，不要当失败。路径打开前先把选择器文件拷入 filesDir。外部 URI 直传易落到笼统 ERROR。预览与编辑共用一个封装，只差布尔参数。

四、回传如何改变等待语义

显式设置 wpsTransferType = TransferType.URI（或 FD）后，Promise 会等到用户关窗；result.data.fileUri 在 WPS 沙箱，必须拷贝到本应用目录再上传。均未设置回传时，仅拉起 WPS，不等待关窗。

req.wpsTransferType = TransferType.URI;
const result = await WPSApi.sendRequest(req);
// 拷贝 result.data.fileUri → 本应用 filesDir

开了回传时 UI 提示「请关闭文档后再返回」。Facade 建议同时返回 result 与 localPath。并发打开时拷贝目录按时间戳隔离。清理临时文件失败不应挡住已得到的本应用路径。日志固定打：是否已注册、是否开回传、code/msg。

五、联调清单

1. 注册 OK（正式包包名再验）
2. 沙箱只读打开（验证 sendRequest 成功路径）
3. enableEdit = true
4. （可选）URI 回传 + 拷贝
5. 故意未注册调用一次，确认进 catch

Code Review 看四项：是否绕开 ensureRegistered、是否打印 secret、是否外部路径直传、是否忽略 .catch。每步只改一类行为，失败时先回滚到上一绿点。

六、协作与复测

PR 勾选：HAR 版本、包名、是否走统一 Facade、Release 无 secret。产品口头「要能打开」时，落到：注册是否绿、路径是否在沙箱、是否要回传。周五用正式包再跑：注册 → 只读 → 可编辑 →（可选）URI。

日志固定打：是否已注册、enableEdit、是否开回传、code/msg、包名后缀。缺任一项，群聊容易反复猜。新人 Onboarding 按「先门禁、再打开、再回传」走，比一天堆满策略开关更少挫败。客服工单把「打不开」「不能编辑」「一直转圈」拆开。真机用例标题写清是否开回传。同一工程多渠道包时提前列全 Bundle 名。

七、小结

WPS Open SDK 鸿蒙版的调用范式 = WPSApi 单例 + 先注册 + sendRequest Promise + 按 Result 分支。把差异收在 Facade，页面只传路径与策略对象。字段以官方对接文档为准；换 HAR 后 clean；正式包包名复测注册。

坚持分层联调，比一次堆满开关更省时间。把「未注册禁止 sendRequest」「回传先拷贝」「必须处理 then/catch」写进联调页，新人合入会稳很多。细节更新时先改 Facade，再改页面。再强调：1013 优先核对包名与 HAR；只读与可编辑用同一封装；开了回传就要接受「等关窗」语义。接入评审把这三句话写进检查表，比事后补洞更省成本。把清单跑两周，入口相关反复提问通常会下降。范式目标是调用面稳定，策略字段要加就单独建用例与 PR，联调才可归因。

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