HarmonyOS WPS Open SDK 实践：setWpsFileToken 与专业版序列号注入

用户093407773514
30 阅读5分钟

HarmonyOS 生态里，行业应用要在端内打开 Office 文档，WPS Open SDK 统一版把专业版（ToB）与个人版（ToC）收成同一套 WPSApi。注册门禁两边都要走 registerApp，差异出现在下一步：ToB 通常必须在成功回调里调用 setWpsFileToken，否则专业版客户端可能打不开文档；ToC 注册 OK 即可打开，不要多写序列号。本文从架构角度把 Token 收成独立授权层，用 SdkConstants.isPersonalSdk() 做运行时分支，并清掉 OpenFileRequest.wpsToken 旧写法。

阅读建议：已了解鸿蒙 Ability 生命周期，并完成过一次 HAR 集成。

为什么序列号必须独立成层

以往痛点是：打开页把 YOUR-PRO-SN 写进 request.wpsToken，调试包碰巧成功，正式包换成另一套 HAR 后客户端拒开。统一版并没有取消序列号，只是把推荐入口固定为全局方法。调用模型应写成：

HAR → registerApp → (ToB) setWpsFileToken → OpenFileRequest → sendRequest → Result
形态registerAppsetWpsFileToken
ToB（专业版）必须注册成功回调中设置
ToC（个人版）必须不需要

用 SdkConstants.isPersonalSdk() 判断，不要用包名猜测。全仓搜索 request.wpsToken 并清理，是迁移时的高频漏项。激活序列号与 appKey 不是同一申请渠道：凭据走 SDK 对接邮箱，专业版序列号走商务 / 技术支持，格式常见为五段连字符。

官方调用与运行时分支

入口签名是 WPSApi.setWpsFileToken(token: string)。一次设置，后续打开自动携带。对接文档写明：同时写全局 Token 与 request.wpsToken 时以全局为准，所以 Request 字段只会造成误导。

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

let sdkReady = false;

export function bootstrapWps(
  appKey: string,
  appSecret: string,
  proSn?: string
): void {
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (r: Result) => {
      if (r.code !== ResultCode.OK) {
        console.error('[WPS] register', r.code, r.msg);
        return;
      }
      if (!SdkConstants.isPersonalSdk() && proSn) {
        WPSApi.setWpsFileToken(proSn);
      }
      sdkReady = true;
    },
  });
}

ToC 分支不要传入占位 SN，也不要调用空字符串的 setWpsFileToken。ToB 分支把 SN 放进构建配置，Release 禁止打印完整值。1013 出现时暂停序列号实验：它是凭据 / 包名问题，先对齐 Bundle 与 HAR，再验证 Token。

打开层只消费就绪态

Ability 启动阶段完成注册与（ToB）注入，页面只调用 sendRequest。若产品要求离线下也能看到按钮，可用 sdkReady === false 时禁用并展示「文档能力初始化中」。

import { common } from '@kit.AbilityKit';
import { WPSApi, OpenFileRequest, Result } from '@wps/wps_sdk';

export async function openAfterReady(
  ctx: common.UIAbilityContext,
  path: string
): Promise<Result> {
  if (!sdkReady) {
    throw new Error('WPS not registered');
  }
  const req = new OpenFileRequest(ctx, path);
  return WPSApi.sendRequest(req);
}

工程结构上拆两个文件：WpsBootstrap.ts 只做注册与 Token；WpsOpenHelper.ts 只做路径、enableEdit、回传。不要在 Helper 里再次 setWpsFileToken，否则启动路径与点击路径会各写一次。

联调地图：从 1013 到未注入

错误分流顺序：HAR / Bundle → 注册 → Token → 打开参数。1013 时把 Bundle 打印值与申请归档并排对照。注册 OK 后再验证只读打开。ToB 确认 setWpsFileToken 已在成功回调执行；ToC 确认没有多余的 SN 注入。

检查项ToBToC
集成匹配 HAR必须必须
registerApp必须必须
setWpsFileToken注册 OK 后设置不需要
OpenFileRequest.wpsToken删除忽略
OpenFileRequest同形态同形态

联调清单建议贴进检查表：

  • 冷启动能打到注册 OK
  • ToB：成功回调里已调用 setWpsFileToken
  • ToC：仓库无 setWpsFileToken 误调用
  • 全仓无 request.wpsToken 残留
  • 只读打开与可编辑打开共用同一 helper

调试包与商店包 Bundle 不同时，凭据分开申请；专业版序列号也要按当前客户端核对。路径类型不一致时先拷贝到沙箱再传入 OpenFileRequest。

实践建议

不要在多个页面分叉注入。出现打开异常时，先区分「未注册」与「打开非 OK」：前者修门禁，后者再查序列号、路径与客户端。HAR 批次变更后，先只替换依赖并重跑注册、Token、只读打开，确认身份无回归再恢复高级参数。

若本周只完成注册与 Token，下周再按可编辑 → 策略字段 → 回传递增，每层保留成功与失败日志各一份。把对接文档入口写进 README 与内部 Wiki，避免每人收藏不同版本的链接副本。HarmonyOS WPS Open SDK 把「文档二开」收敛成一条可重复的调用链，但 ToB 链上仍缺不了 setWpsFileToken。

发版评审建议把这四列贴进检查表：HAR、Bundle、注册 code、是否已设 Token。比临发口头确认更稳。换 HAR 后全量编译，确认业务代码 import 均来自 @wps/wps_sdk。

水印、extraOptions、回传不要和 Token 写在同一个点击回调里。ToB 注入失败时，打开层应保持禁用，而不是降级成「先打开再补 SN」：全局 Token 的语义是注册成功后一次写入，中途补写会让日志无法判断哪一次生效。ToC 工程如果从 ToB 示例拷贝了 PRO_SN 占位符，运行时会被 isPersonalSdk() 跳过，但仓库里仍会留下误导性常量，评审时应删掉。

调试包与商店包不要共用同一份序列号配置文件。和凭据一样，SN 按 flavor 隔离，提交仓库时用空占位，本地覆盖。远程协助时一次提供：isPersonalSdk() 返回值、是否调用 setWpsFileToken、注册 code/msg、Bundle 打印值。这四项齐了，才能判断是形态分支写错还是客户端未授权。

统一版把打开收敛成一条链，但 ToB 链头在注册之后还多一步授权。把这一步从页面生命周期里抽出来，页面只关心 sdkReady，比在每个 OpenFileRequest 上重复赋值更稳。字段与错误码以官方对接文档为准，随 SDK 批次核对后再合入。

技术交流 QQ 群：628436767。申请 SDK HAR 与凭据时注明包名与专业版 / 个人版需求。

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

avatar
文章
阅读
粉丝