问 <p>集成 WPS Open SDK 鸿蒙统一版前，建议先过一遍下面 FAQ，避免选型与凭据错误导致

集成 WPS Open SDK 鸿蒙统一版前，建议先过一遍下面 FAQ，避免选型与凭据错误导致联调反复返工。统一版把专业版与个人版的 TypeScript API 对齐到同一套 HAR 体系，但凭据、客户端版本、Token 与不落地策略仍按 ToB/ToC 分叉。不少项目卡在 1013 或「能打开不能编辑」，根因往往是版本配对错误，而不是 API 调用写法。本文按版本关系、共用代码、申请接入、高频坑四条线浓缩回答，适合已确定要上 WPS 二开、需要快速对齐口径的 HarmonyOS 开发者。

统一版、个人版 WPS 与共用代码

统一版在保留专业版能力基础上增加 ToC 个人版支持，不是下架旧 SDK。ToB 项目继续申请专业版 HAR；ToC 对接用户设备上的 WPS 个人版，注册成功即可打开，无需激活序列号（setWpsFileToken）。

API 层可高度复用；须分叉的是：HAR 与凭据、ToB 注册后 setWpsFileToken、不落地仅 ToB 生效。用 SdkConstants.isPersonalSdk() 判断。个人版侧主要是文档不落地及关联的云文档/分享/打印限制；打开、编辑、水印、关闭回传等核心能力均支持（以所申请 HAR 为准）。

如何获取 SDK 与接入五步

向 WPS 提供应用名、Bundle 包名、版本类型（ToB/ToC）、用途。凭据与包名绑定，换包名须重新申请。专业版激活序列号另向商务/技术支持申请，在 registerApp OK 后 setWpsFileToken，勿写入每次 OpenFileRequest。

接入顺序建议固定为：

1. 集成 HAR（`@wps/wps_sdk`）

2. 启动时 `registerApp`，处理 1013

3. （ToB）OK 后 `setWpsFileToken`

4. 文件入沙箱 → `OpenFileRequest`

5. 可选配置 `wpsTransferType` 做关窗回传

多环境（内测/正式）包名不同时，凭据不能共用。密钥勿硬编码进公开仓库；政企项目可用配置中心或构建 flavor 注入。

高频坑与时序

- 未注册完成就 sendRequest → 异常，须 catch，不能仅靠 result.code

- enableEdit 默认只读 → 显式 true 可编辑

- 系统 URI 未拷沙箱 → ERROR

- OK 且无 data → 未开回传或未关窗，非失败

- 混用 ToB/ToC HAR → 1013 或打开失败

registerApp 与 OpenFileRequest 须严格先后；冷启动用户快速点击「打开」会触发未注册异常。建议在 UI 层增加 wpsReady 状态，注册完成前禁用打开入口。HarmonyOS 上 WPS 与应用生命周期不同步，回传测试须「关闭文档窗口」，仅切回应用不算。

if (!SdkConstants.isPersonalSdk()) {
  WPSApi.setWpsFileToken(SN);
}

从旧专业版升级统一版时，除替换 HAR 外应回归：Token 注入时机、不落地开关、水印与 extraOptions 组合。售前承诺「一套包打天下」时，研发侧务必澄清：API 统一不等于凭据通用。

小结

先定 ToB/ToC 与是否不落地，再申 HAR 与凭据；统一版降低 API 分裂，不取消版本配置差异。把注册时序与沙箱路径写进团队 checklist，可减少一半联调往返。

更多参数见官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT

技术交流 QQ 群：628436767