HarmonyOS WPS Open SDK 二开指南：ResultCode 分层处理与联调排错

用户093407773514
11 阅读4分钟

在 HarmonyOS 上为 ToB 政企或 ToC 个人应用集成 WPS Open SDK 时，文档能力往往走「注册 → 打开 →（可选）关闭回传 → 上传业务后端」链路。这条链路上任何一环返回非预期状态，都需要开发者读懂 Result 里的 code 与 msg。WPS Open SDK 鸿蒙统一版将专业版与个人版 API 对齐，错误码语义也统一在 ResultCode 枚举中。本文从架构视角说明如何分层处理成功、SDK 错误码与 Promise 异常，并给出可复用的 TypeScript 示例。

背景：为何不能只判断 truthy

WPSApi.sendRequest 返回 Promise<Result>。很多项目写成「有 result 就算成功」，这在以下场景会踩坑：

  • ResultCode.OK 且 data 为空：未配置回传时仅表示 WPS 已拉起
  • ResultCode.ERROR：仍在 resolve 里，若不判断 code 会误进成功逻辑
  • 未调用 registerApp 或注册未完成：Promise reject，.then() 不会执行

因此错误处理应分为三层：注册鉴权层、打开/回传业务层、运行时异常层。

ResultCode 语义矩阵

code常量层级处理建议
0OK业务根据 data 区分仅打开 vs 回传成功
-1NONE—不应作为终态，检查 SDK 版本与调用方式
-2ERROR打开查路径、参数、WPS 是否安装可用
1013ERROR_CODE_AUTH_FAILURE注册查 appKey/secret、包名绑定
>0（业务码）回传记录 msg，勿用旧 filePath
throw—前置保证 registerApp 先于 sendRequest

Result 还携带 requestType，便于在同一 handleResult 中区分是注册回调还是打开回调，避免把 1013 当成打开失败。

注册与打开：1013 和 ERROR

RegisterAppRequest 传入 appKey、appSecret 后，失败最常见即 ERROR_CODE_AUTH_FAILURE。除密钥错误外，包名与申请时不一致是政企项目高发问题：内测包、商店包、定制 ROM 预装包若 bundleName 不同，须分别申请凭据。

个人版（ToC）注册 OK 后即可 OpenFileRequest；专业版（ToB）还需 setWpsFileToken，且官方建议放在 registerApp 成功回调中，而非每次打开时传 wpsToken。注册失败时继续打开，只会得到 ERROR 或异常，浪费联调时间。

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

export async function ensureWpsRegistered(ctx: common.UIAbilityContext): Promise<void> {
  const req = new RegisterAppRequest(ctx, APP_KEY, APP_SECRET);
  const result = await WPSApi.sendRequest(req);

  if (result.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
    throw new Error('WPS 凭据校验失败，请核对 appKey/appSecret 与包名');
  }
  if (result.code !== ResultCode.OK) {
    throw new Error(result.msg ?? `WPS 注册失败 code=${result.code}`);
  }

  if (!SdkConstants.isPersonalSdk()) {
    WPSApi.setWpsFileToken(process.env.WPS_TOKEN ?? '');
  }
}

打开层：ERROR 与沙箱路径

ResultCode.ERROR 涵盖参数不完整、不支持的请求类型、打开异常等。对接文档强调：从系统选择器获得的文件应先拷贝到应用沙箱，再构造 OpenFileRequest。若直接把 content URI 或无权限路径传入，容易在 ERROR 分支反复试错。

只读与可编辑由 enableEdit 控制，默认只读；二开编辑场景须显式 enableEdit = true。这与错误码无直接对应，但「用户反馈无法编辑」常被误判为 SDK 故障，实为参数未开。建议在 ERROR 分支把 result.msg 原样写入日志，便于与 WPS 侧 support 对账。

import { OpenFileRequest, ResultCode, WPSApi } from '@wps/wps_sdk';

export async function openForEdit(ctx: common.UIAbilityContext, sandboxPath: string) {
  await ensureWpsRegistered(ctx);

  const req = new OpenFileRequest(ctx, sandboxPath);
  req.enableEdit = true;

  const result = await WPSApi.sendRequest(req);
  if (result.code === ResultCode.ERROR) {
    throw new Error(result.msg ?? '打开文档失败');
  }
  if (result.code !== ResultCode.OK) {
    throw new Error(`WPS 异常 code=${result.code}`);
  }
  return result;
}

回传、异常与可观测性

配置 wpsTransferType 为 URI 或 FD 后，关闭文档才会填充 ResultData。成功：code === OK 且 data.fileUri 或 data.transferFd 有值。回传失败：code 为非零正整数，应提示用户重试或联系支持，并打全量日志。切勿在 code !== OK 时仍用打开前的路径上传——这是生产环境「已保存但服务器是旧文件」的常见根因。

文档明确：registerApp 回调 OK 之前调用 sendRequest 会抛异常。这类错误不会出现在 result.code 里，必须用 .catch() 或 try/catch。应用冷启动时若 UI 渲染早于注册完成，用户快速点击「打开文档」就会触发。做法包括：注册完成前禁用按钮、全局 isWpsReady 标志、或在 open 前 await 注册 Promise。

工程上建议统一日志格式 [WPS] requestType= code= msg=，对用户展示映射表而非裸码。联调环境可 Mock OK、ERROR、1013、回传失败等分支，验证 UI 与上传队列是否与 code 一致。与 extraOptions、水印、不落地等配置变更应隔离排错，一次只改一个变量，否则 ERROR 时难以定位根因。

小结

HarmonyOS WPS 二开的质量很大程度取决于 ResultCode 是否被完整处理：注册看 1013，打开看 ERROR，回传看 OK 与正整数业务码，时序问题看 Promise 异常。统一版 SDK 便于一套错误处理覆盖 ToB/ToC，但包名凭据与专业版 Token 仍是独立配置项。

在团队实践中，我们会把 ensureWpsRegistered 与 handleWpsResult 沉淀到 @wps/wps_sdk 之上的 thin wrapper 模块，业务页面只关心三种用户态：「文档已打开」「回传文件已就绪」「可重试的失败」。上传模块订阅回传成功事件，而不是在打开按钮回调里假设 data 一定有值。对政企交付物，还会把 code/msg 写入本地诊断日志，方便驻场同事导出给后端排查。

建议团队将注册、打开、回传三条链路的错误码用例写入 instrumented test 或手工测试用例表，每次升级 HAR 或 WPS 客户端版本后回归一遍，避免小版本变更导致 msg 文案变化而 UI 映射过时。对驻场项目，还可把典型 ERROR 的 msg 整理成内部 wiki，缩短新人上手时间。这样联调时间能从「猜原因」缩短为「对表排查」，上线后工单量也会明显下降。

阅读建议：已了解鸿蒙 Ability 与 Promise 基础。
官方对接文档：金山文档「WPS Open SDK 鸿蒙对接文档」
技术交流 QQ 群：628436767

avatar
文章
阅读
粉丝