HarmonyOS WPS Open SDK 实践：用 SdkConstants 判断当前 HAR 形态

接入 @wps/wps_sdk 时，页面最容易写成「打开前 if 一下 WPS 包名」。统一版对外 API 一致，但 ToB 专业版 HAR 与 ToC 个人版 HAR 仍是两份包 ，凭据不可混用。官方给出的运行时入口是 SdkConstants.isPersonalSdk()：true 走个人版路径，false 走专业版路径。阅读建议：已了解 registerApp 与 Promise。把判断收进 Facade，再决定要不要 setWpsFileToken，联调会少绕很多弯路。

判断的是 HAR，不是桌面图标

设备上的 WPS 客户端渠道，和编译进三方应用的 HAR，是两条线。猜包名会在换机、换企业渠道包、WeLink 包时全面失真。isPersonalSdk() 读的是 当前进程加载的 SDK 包，不读桌面应用名。

问题	该问谁	不该问谁
这份 HAR 是个人版还是专业版	`SdkConstants.isPersonalSdk()`	`bundleName` 字符串包含 "wps"
凭据是否匹配	`registerApp` → 1013	再点一次打开
客户端要不要升级	`wpsUpdateInfo`	用弹窗结果当 HAR 类型

个人版路径通常注册成功即可打开，不必 setWpsFileToken。专业版常在注册 ResultCode.OK 后注入序列号。同一仓库兼两套 flavor 时，用构建变体注入 key/secret/sn；页面只调 Facade。Code Review 盯两件事：个人版路径是否误依赖 Token，专业版路径是否漏设 Token。

把 isPersonalSdk() 写进新人 Onboarding 的起始页（先讲 WPSApi 门禁，再讲 HAR 判断）：先认 HAR，再谈 OpenFileRequest 字段。联调群里「设了 enableLocalization 没效果」优先查是不是个人版 HAR------该字段在 ToC 设置后不生效。若同一周既验 ToB 又验 ToC，建议分机或分日，避免 HAR/凭据串包。串包后的 1013 排查成本往往高于重装。

Facade：查询 + 注册 + Token

typescript 复制代码

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

let ready = false;

export function sdkFlavor(): 'personal' | 'pro' {
  return SdkConstants.isPersonalSdk() ? 'personal' : 'pro';
}

export async function ensureWps(
  ctx: UIAbilityContext,
  cred: { key: string; secret: string; sn?: string }
) {
  if (ready) return;
  const r = await WPSApi.sendRequest(
    new RegisterAppRequest(ctx, cred.key, cred.secret)
  );
  if (r.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
    throw new Error('1013: key/secret/bundle/HAR');
  }
  if (r.code !== ResultCode.OK) throw new Error(`register ${r.code}`);
  if (!SdkConstants.isPersonalSdk() && cred.sn) {
    WPSApi.setWpsFileToken(cred.sn);
  }
  ready = true;
}

也可用 WPSApi.registerApp(..., { onCallback })。包名与凭据绑定；换 HAR 后 clean。Release 不打印 secret。未注册就 sendRequest 会进 catch。打开按钮在 ready 前禁用。调试包建议打：flavor= + sdkFlavor() + 包名后缀。限时凭据失效需重新申请，不要用业务重试掩盖 1013。

注册失败时不要继续叠编辑与回传。Token 只在专业版分支 注入。进程内缓存 ready 即可。Ability 启动阶段完成 ensure，比在点击回调里临时注册更稳。真机日志固定一条：ready + isPersonalSdk() + 包名后缀。

不要在每个页面写 if (SdkConstants.isPersonalSdk())。全仓只允许 adapter 出现该调用。否则产品改默认策略时要搜十几处。

打开时只消费 Facade 结果

typescript 复制代码

export async function openDoc(
  ctx: UIAbilityContext,
  path: string,
  opts: { edit?: boolean; noLanding?: boolean } = {}
) {
  await ensureWps(ctx, CRED);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = !!opts.edit;
  if (typeof opts.noLanding === 'boolean' && !SdkConstants.isPersonalSdk()) {
    req.enableLocalization = !opts.noLanding;
  }
  const result = await WPSApi.sendRequest(req);
  if (result.code !== ResultCode.OK) {
    throw new Error(`${result.code}: ${result.msg ?? ''}`);
  }
  return result;
}

外部文件先入 filesDir。预览 edit: false；编辑再开。不落地相关开关只在专业版 HAR 生效，个人版赋值会被忽略------所以判断必须发生在赋值前，而不是赋值后看现象反推。页面不要散落三套 open；全仓搜 new OpenFileRequest 尽量为一。

extraOptions 与水印两端都可用，但不要和 flavor 判断写在同一层 if 里。flavor 决定「哪些字段允许写」；产品开关决定「写什么值」。混在一个巨大 if 里，Code Review 读不动。

联调对照

确认 libs/wps_sdk.har 与申请渠道（专业版 / 个人版）一致，clean 重编
日志 sdkFlavor() 与预期一致
专业版：注册 OK 后 Token 已设；个人版：确认未设
沙箱只读打开
可编辑；（可选）URI 回传拷贝
故意未注册确认 catch；正式包包名再验 1013

现象	优先查
1013	HAR 渠道、包名、key/secret 是否一套
打开失败但注册 OK	专业版是否漏 Token
不落地无效	是否个人版 HAR
抛异常	是否未注册
只能预览	`enableEdit`

同一仓库两套 flavor，用 product 注入 CRED，不要运行时读文件名。凭据按包名分目录。周五正式包再跑：flavor 日志 → 注册 → 只读 → 可编辑。PR 勾选：是否绕开 Facade、是否页面层直接调 isPersonalSdk、Release 无密钥。

客服工单把「打不开」拆成：flavor 是否认对、注册是否绿、路径是否沙箱、是否要 Token。新人按「先认 HAR，再门禁，再打开」走，比一天堆满 extraOptions 更少挫败。若联调机装了多个 WPS 客户端，仍以 isPersonalSdk() 为准，不要改去解析包名「作为双保险」------双保险会变成双错误。

构建侧每个 product 指向自己的 libs/wps_sdk.har 与凭据模块，业务页只 import CRED。调试包与正式包 bundleName 不同就必须两套 key。换 HAR 后如果没 clean，日志里的 sdkFlavor() 会对不上磁盘文件，这种问题优先 rebuild 而不是改打开参数。OpenFileRequest.wpsToken 即使存在也不推荐；全局 setWpsFileToken 更不容易漏。若产品要在运行时展示「当前接入包类型」，只允许读 Facade 的 sdkFlavor()，不要在页面再调一遍 Constants。

把 flavor 写入非敏感诊断信息（崩溃日志、反馈邮件模板），不要写 secret 与完整序列号。Code Review 遇到业务文件里的 isPersonalSdk 直接打回。同一 PR 不要同时改 flavor 分支和 extraOptions 默认值，否则失败无法归因。真机用例标题写清：pro-readonly / personal-edit / pro-token-missing。周五正式包再跑一遍，比只在调试包点通过更接近线上。

小结

HarmonyOS 上判断当前 WPS Open SDK 形态，标准动作是 SdkConstants.isPersonalSdk()，并且只放在 Facade 。它区分的是 HAR，不是用户装了哪个 WPS。专业版在注册成功后 setWpsFileToken；个人版跳过。不落地等字段按 flavor 决定是否赋值。字段语义以官方对接文档为准。

把「禁止解析 WPS 包名」「全仓一次 isPersonalSdk」「换 HAR 必须 clean」写进 Onboarding。坚持两周清单，串包类 1013 会明显下降。策略字段要加就单独 PR，不要和 flavor 分支搅在一起。欢迎在评论区补充真机 isPersonalSdk() 与客户端包名对照，方便后来人建立直觉------对照归对照，代码仍只信 Constants。

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