HarmonyOS WPS Open SDK 接入 FAQ:从版本配对到文档边界

12 阅读5分钟

同一个“文档打不开”,可能来自四种完全不同的原因:申请的 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 虽然能编译,但容易漏设,也不利于审计。

如果全局设置和请求字段同时存在,排查时很难判断最终采用哪一个值。统一规则更简单:

  1. 应用初始化负责注册与序列号。
  2. 文档服务负责路径、编辑模式和回传参数。
  3. 页面只消费就绪状态和打开结果。

这也是统一版对工程团队最有价值的部分:版本差异可以被配置层吸收,业务侧不需要复制两份文档调用代码。

四、文件边界与打开模式

文件必须先位于应用可访问的沙箱路径。外部 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