在 HarmonyOS 业务应用里接入 @wps/wps_sdk，很多项目的目标很直接：用户能在应用内打开 Word / Excel / PPT，必要时可编辑，关窗后结果回到本应用。对接文档把这条路径写得很清楚——先注册成功，再 sendRequest；文件先进入本应用沙箱，再构造 OpenFileRequest。本文按调用链把轻量接入跑通，字段语义以官方对接文档为准。

一、轻量路径在调用链中的位置

推荐时序：registerApp / RegisterAppRequest 成功 → 文件拷入本应用沙箱 → 构造 OpenFileRequest（按需 enableEdit）→ sendRequest →（可选）关窗回传后拷贝。

层级	目标	主要入口
接入	鉴权通过	RegisterAppRequest
打开	预览 / 编辑	OpenFileRequest + enableEdit
路径	可被 WPS 读取	本应用沙箱路径
结果	关窗拿回文件	wpsTransferType + 拷贝

轻量路径的特点是：注册成功后即可打开，不必在每次打开前再叠一长串策略字段。联调时仍建议「先绿可打开，再开编辑，最后才开回传」，避免一次堆满开关导致 ResultCode.ERROR 难归因。

二、注册：未就绪就打开会进 catch

未注册完成就 sendRequest 会 reject，须 try/catch。appKey / appSecret 与 bundleName 绑定，调试包与正式包包名不同须分别申请，否则常见 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;
}

把 ensureRegistered 放进 Ability 启动或文档页 aboutToAppear，打开按钮在就绪前禁用。日志区分「注册失败」与「打开失败」。换 HAR 后 clean；Release 不打印 secret。正式包包名再验一次注册。

同一工程多渠道包时，凭据按包名分目录存放，避免调试包密钥误入正式包。注册失败返回 1013 时，优先核对 bundleName 是否与申请材料一致，再查 HAR 是否装对。限时凭据失效需重新申请，不要在业务层硬编码「再试一次」掩盖鉴权问题。

三、打开：沙箱路径 + enableEdit

路径打开前，先把选择器 / 下载文件拷入 filesDir。外部 URI 直传易落到笼统 ERROR。enableEdit 未设或 false 为只读；需要编辑再显式设 true。

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);
}

预览与编辑共用一个封装，只差布尔参数，避免页面散落多套 new OpenFileRequest。页面层不要自己猜 data：未开回传时 OK 且 data 空属正常。

部分策略字段（例如不落地相关开关）在当前凭据约定下可能不生效；轻量联调先不要依赖它们做验收，以免误报「SDK 坏了」。需要细控菜单、水印时，以对接文档对该字段的生效说明为准，再单独加用例。

联调「只能看不能改」时，先确认本次请求是否写入 enableEdit = true，再查客户端是否被策略限制。不要把注册失败与打开失败混在同一条 toast。

四、可选回传：关窗后必须先拷贝

若业务要拿回编辑结果，显式设置 wpsTransferType = TransferType.URI（或 FD）。Promise 会等到用户关窗；result.data.fileUri 在 WPS 沙箱，必须拷贝到本应用目录再上传 / 归档。

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

开了回传时 UI 提示「请关闭文档后再返回」，避免用户以为卡住。Facade 建议同时返回 result 与 localPath，业务只消费本应用路径。并发打开时拷贝目录按时间戳隔离。

五、联调清单

1. 注册 OK（正式包包名再验）
2. 沙箱只读打开
3. enableEdit = true 可编辑
4. （可选）URI 回传 + 拷贝
5. 换 HAR 后 clean；Release 无 secret 日志

现象	优先查
1013	key/secret/包名/HAR
只能预览	enableEdit
笼统 ERROR	路径是否在本应用沙箱
OK 且 data 空	是否未开回传
一直转圈	开了回传是否还在等关窗

Code Review 看四项：是否绕开 ensureRegistered、是否打印 secret、是否外部路径直传、是否一次堆满策略导致无法归因。

六、协作与复测

PR 勾选：HAR 版本、包名、是否走统一打开封装。产品口头「要能改」时，落到字段：是否 enableEdit、是否要回传。周五用正式包再跑：注册 → 只读 → 可编辑 →（可选）URI 拷贝。

日志固定打：是否已注册、enableEdit、是否开回传、code/msg、包名后缀。缺任一项，群聊容易反复猜。新人 Onboarding 按分层走，比一天堆满所有开关更少挫败。

客服工单把「打不开」「不能编辑」「一直转圈」拆开：分别对应注册/路径、enableEdit、回传等待语义。真机用例标题写清是否可编辑、是否开回传，避免结果被混读。若产品临时要求叠更多策略字段，PR 必须写明为何加、以及联调如何归因。

同一工程多渠道包时提前列全 Bundle 名，换包名要重申凭据。注释写清「未注册禁止 sendRequest」「外部文件先入沙箱」。清理临时文件失败不应把用户带到失败页——本应用路径已经可用。把清单跑两周，路径相关反复提问通常会下降。

七、小结

轻量接入 = 注册就绪 + 沙箱路径 + 按需编辑 + 可选回传拷贝。把差异收在 Facade，页面只传路径与策略对象。字段以官方对接文档为准；换 HAR 后 clean；正式包包名复测注册。

坚持分层联调，比一次堆满开关更省时间。把「先注册再打开」「路径先入沙箱」「回传先拷贝」写进联调页，新人合入会稳很多。细节更新时先改 Facade，再改页面。

再强调：1013 优先核对包名与 HAR；只读与可编辑用同一封装；开了回传就要接受「等关窗」的等待语义。接入评审把这三句话写进检查表，比事后补洞更省成本。

---

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