同一个“文档打不开”,可能来自四种完全不同的原因:申请的 SDK 包和客户端不匹配、应用还没有注册成功、文件不在业务沙箱内,或者请求根本没有开启需要的能力。把这些现象都归到 OpenFileRequest 上,联调就会变成参数排列组合。更工程化的做法是把 FAQ 组织成故障树,从交付物、初始化、请求和结果四个层级依次排除。
本文以 HarmonyOS 接入 @wps/wps_sdk 为背景,整理团队最常问的问题。重点不是背接口,而是明确每个问题应该在哪一层解决,以及哪些差异应该收口到配置,避免散落到业务页面。
一、先确认版本与 HAR 是否配对
WPS Open SDK 鸿蒙统一版覆盖两种客户端环境,API 形态一致,但申请时必须明确所需版本。HAR、appKey、appSecret 与包名属于同一套交付信息,不能跨批次混用。
| 问题 | 正确理解 | 排查动作 |
|---|---|---|
| 能否共用一套调用代码 | 可以,核心入口和请求模型一致 | 差异收口到初始化配置 |
| 为什么换包名后失败 | 凭据与 Bundle 包名绑定 | 重新确认申请记录 |
| 为什么换 HAR 后异常 | 可能是缓存或批次不匹配 | clean 后重新安装依赖 |
| 如何判断当前版本 | 使用 SdkConstants.isPersonalSdk() | 不要通过 WPS 包名猜测 |
工程上建议把版本选择放在构建配置,而不是让每个页面判断。业务层只看到“是否需要激活序列号”这一项配置,不需要知道当前包来自哪次交付。
二、注册是状态机,不是一次函数调用
WPSApi.registerApp(appKey, appSecret, callback) 的回调结果决定应用是否就绪。调用动作本身不代表成功,只有 ResultCode.OK 才能解锁后续请求。对于页面频繁创建、按钮可能连点的应用,初始化模块应至少包含 idle、booting、ready 三种状态。
import { WPSApi, Result, ResultCode } from '@wps/wps_sdk';
let ready = false;
let booting: Promise<void> | null = null;
export function bootWps(config: {
appKey: string;
appSecret: string;
activationSn?: string;
}): Promise<void> {
if (ready) return Promise.resolve();
if (booting) return booting;
booting = new Promise<void>((resolve, reject) => {
WPSApi.registerApp(config.appKey, config.appSecret, {
onCallback: (result: Result) => {
if (result.code !== ResultCode.OK) {
booting = null;
reject(new Error(`register ${result.code}: ${result.msg ?? ''}`));
return;
}
if (config.activationSn) {
WPSApi.setWpsFileToken(config.activationSn);
}
ready = true;
resolve();
},
});
});
return booting;
}
这个 Promise 会合并并发调用,失败后允许重试。它同时把“序列号是否需要设置”变成可选配置,业务页不必写版本分支。注册日志中应保留 code/msg、Bundle 和 HAR 批次,但不要输出完整密钥。
三、序列号为什么推荐全局设置
需要 WPS 产品授权的交付环境,推荐在注册成功回调中调用 WPSApi.setWpsFileToken(token)。一次设置后,后续请求自动携带。把序列号写进每个 OpenFileRequest.wpsToken 虽然能编译,但容易漏设,也不利于审计。
如果全局设置和请求字段同时存在,排查时很难判断最终采用哪一个值。统一规则更简单:
- 应用初始化负责注册与序列号。
- 文档服务负责路径、编辑模式和回传参数。
- 页面只消费就绪状态和打开结果。
这也是统一版对工程团队最有价值的部分:版本差异可以被配置层吸收,业务侧不需要复制两份文档调用代码。
四、文件边界与打开模式
文件必须先位于应用可访问的沙箱路径。外部 URI 的临时授权可能在页面切换后失效,因此推荐先复制到业务目录,再构造请求。下面的 helper 把注册、路径和模式放在同一条调用链里:
import { common } from '@kit.AbilityKit';
import { OpenFileRequest, Result, ResultCode, WPSApi } from '@wps/wps_sdk';
import { bootWps } from './WpsBootstrap';
export async function openDocument(options: {
context: common.UIAbilityContext;
path: string;
appKey: string;
appSecret: string;
editable: boolean;
}): Promise<Result> {
await bootWps({ appKey: options.appKey, appSecret: options.appSecret });
const request = new OpenFileRequest(options.context, options.path);
request.enableEdit = options.editable;
try {
const result = await WPSApi.sendRequest(request);
if (result.code !== ResultCode.OK) {
console.error('[WPS] open rejected', result.code, result.msg);
}
return result;
} catch (error) {
console.error('[WPS] open exception', error);
throw error;
}
}
enableEdit 不设置时按只读处理。因此“文档只能预览”不是 SDK 能力缺失,而是请求模式没有显式开启。路径错误则通常表现为 Result.code 非零;注册时序错误更可能进入 Promise 异常分支。把二者混在同一个 Toast 中,会丢失最重要的定位信息。
五、Result.data 为空是否代表失败
不一定。没有开启关闭回传时,WPS 成功拉起就会返回 ResultCode.OK,此时没有编辑结果需要回传,data 为空是正常语义。开启回传后,用户关闭文档并回传成功,才应检查 data 中的 URI、FD、文件名或大小。
验收时建议拆成四个档位:
| 档位 | 通过标准 |
|---|---|
| 注册 | 冷启动回调 ResultCode.OK |
| 只读打开 | 请求成功且文档可预览 |
| 可编辑打开 | enableEdit = true 后可修改 |
| 关闭回传 | 用户关闭后拿到结果并完成业务侧转存 |
把“打开”与“回传”分开验收,可以避免把正常空返回误判为 SDK 故障,也能让测试用例更明确。
六、1013 的诊断顺序
1013 是 ERROR_CODE_AUTH_FAILURE,属于接入身份校验失败。遇到它时,优先级最高的是核对:
- 运行时 Bundle 是否与申请凭据时填写的一致。
- HAR 与凭据是否来自同一交付批次。
- 是否把调试配置带入正式构建。
- 凭据是否成对、是否包含空格或已经失效。
如果是 appKey 或 appSecret 为空,常见返回是 ResultCode.ERROR,应检查构建注入;1013 则更偏向身份不一致。不要通过修改水印、修订或回传参数来“修复”认证问题。
七、上线前的 FAQ 复盘
在提测前,团队可以用六个问题快速自检:版本和 HAR 是否配对,注册是否幂等,序列号是否只设置一次,文件是否进入沙箱,只读与可编辑是否分别验证,回传结果是否完成转存。全部通过后,再增加水印、extraOptions 等策略能力。
鸿蒙 WPS 二开并不要求每个业务开发者都熟悉 SDK 内部细节,但需要团队对边界形成一致认识。把版本差异放进配置、把注册做成状态机、把文档请求收进 helper,FAQ 就不会在每次迭代中重复出现。
基于 WPS Open SDK 鸿蒙版对接实践整理,仅供开发者参考。 官方对接文档:365.kdocs.cn/l/clQl5cek2… 技术交流 QQ 群:628436767