在 HarmonyOS 应用里接入 @wps/wps_sdk 时，业务侧常把「打开文档」当成单一验收点。工程推进几周后会发现：不同交付批次的 HAR 与凭据，对激活序列号、enableLocalization 等字段的行为并不完全相同。统一版把调用面收敛到 WPSApi + OpenFileRequest，并不等于「任意 HAR 随便换」。本文按注册 → Token → 打开 → 策略字段的顺序，把差异收进适配层，便于代码评审与联调归因；字段语义以官方对接文档为准。

一、差异落在配置，不落在打开 API

统一版的价值是：同一套 TypeScript 接口覆盖多种交付形态。真正要分叉的通常只有三处：

页面层应只看见 prepare / open。把 HAR 文件名、凭据环境标识、是否注入序列号放进构建配置，比在每个按钮里写 if 更稳。

二、HAR 与凭据：匹配比「能编译」更重要

在 oh-package.json5 中依赖写法一致：

{
  "dependencies": {
    "@wps/wps_sdk": "file:./libs/wps_sdk.har"
  }
}

把交付的 HAR 放进 ./libs/，执行 ohpm install。申请凭据时须注明包名与所需交付形态；凭据与 bundleName 绑定，调试包与正式包名称不同时不能混用。换 HAR 批次后务必 clean，再核对正式包是否仍返回 1013。

常见失败不是「API 写错」，而是「HAR / 凭据 / 真机 WPS 客户端」三者未对齐。联调日志建议固定打印：当前 bundleName、凭据环境标识（勿打明文 secret）、注册 code / msg。

三、注册写成可 await，序列号只在需要时注入

对接文档要求：registerApp 成功之前调用其它 sendRequest 会抛异常。这不是打开失败，而是请求链未就绪。注册成功后，若当前凭据约定需要激活序列号，再调用 setWpsFileToken；不需要时保持跳过。推荐用构建注入的可选参数表达，而不是在业务页猜测。

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

let ready = false;

function prepareWps(
  key: string,
  secret: string,
  activationSn?: string
): Promise<void> {
  return new Promise((resolve, reject) => {
    if (ready) {
      resolve();
      return;
    }
    WPSApi.registerApp(key, secret, {
      onCallback: (result: Result): void => {
        if (result.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
          reject(new Error(`1013: ${result.msg ?? ''}`));
          return;
        }
        if (result.code !== ResultCode.OK) {
          reject(new Error(`register ${result.code}`));
          return;
        }
        if (activationSn) {
          WPSApi.setWpsFileToken(activationSn);
        }
        ready = true;
        resolve();
      },
    });
  });
}

冷启动在 Ability 里 await prepareWps；打开按钮用 ready 控制。Release 不要打印完整 secret。不推荐在每次 OpenFileRequest 上重复塞 wpsToken；全局 setWpsFileToken 更简洁。

四、打开层仍共用一套 OpenFileRequest

无论当前凭据形态如何，打开文档都应走同一函数：沙箱路径 + enableEdit。默认只读；显式 true 才可编辑。需要关窗回传时再赋 wpsTransferType，与可编辑开关独立。

import { common } from '@kit.AbilityKit';
import fs from '@ohos.file.fs';

function toSandbox(ctx: common.UIAbilityContext, src: string): string {
  const dir = `${ctx.filesDir}/wps_diff`;
  fs.mkdirSync(dir, true);
  const dest = `${dir}/${Date.now()}.docx`;
  fs.copyFileSync(src, dest);
  return dest;
}

export async function openDoc(
  ctx: common.UIAbilityContext,
  src: string,
  editable: boolean
): Promise<Result> {
  await prepareWps(APP_KEY, APP_SECRET, ACTIVATION_SN_OR_EMPTY);
  const path = toSandbox(ctx, src);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = editable;
  return WPSApi.sendRequest(req);
}

ACTIVATION_SN_OR_EMPTY 由 flavor / 构建配置注入：需要序列号的变体传真实值，不需要的变体传空字符串，让 prepareWps 跳过 Token。路径务必先落到应用沙箱；外部 URI 权限不足时常见泛化 ResultCode.ERROR。

五、策略字段：先确认是否生效，再谈菜单矩阵

水印、修订、extraOptions、落地相关字段都挂在同一请求对象上。实践里建议按层叠加：

1. 只读打开，验证注册与路径
2. enableEdit = true，验证可编辑
3. 水印 / 修订
4. extraOptions（仅显式赋值生效）
5. 落地相关字段——先确认当前 HAR / 凭据是否支持
6. 回传，关窗后处理 Result.data

一次写满所有开关，出了 ResultCode.ERROR 很难归因。部分交付形态下，落地相关开关设置后不生效，或会连带强制关闭云文档、分享、打印等能力。方案评审时应先确认当前凭据是否允许该能力，再讨论菜单矩阵，否则真机上会出现「改了开关却没变化」。

六、联调清单与工程纪律

建议把下面几条写进 PR 模板：

多人协作时冻结平行 Helper：新需求只扩 Facade 可选参数。合入前用正式包包名再验注册；真机各跑一次只读与可编辑。字段与错误码仍以官方对接文档为准，随 SDK 小版本核对。

七、小结

HarmonyOS 上 WPS Open SDK 的「交付形态差异」，本质是配置与能力边界问题，不是打开 API 数量问题。统一版减少的是页面层分裂，取消不了 HAR / 凭据匹配与序列号注入分叉。把注册和打开收成 prepareWps / openDoc，用构建配置表达是否注入 Token，联调就能从猜原因变成对表排查。申请 HAR 与凭据时注明包名与所需形态；换包后 clean。不要在 Release 打印完整 appSecret，也不要为「另一种交付」再复制一整套打开代码。

再补一段工程侧提醒：接入评审时把「当前 HAR 文件名、凭据环境、是否注入序列号、真机 WPS 构建号」写成一页对照表，贴进需求单。测试同学按表验收，比口头说「都能打开」靠谱。若一周后产品要求预览也带水印或关窗回传，仍然只改 openDoc 可选参数，并把联调用例补一行。这样适配层边界不会被临时需求冲垮。正式包与调试包包名不同时，凭据批次也要分开归档，避免「本地绿、上架红」。换 HAR 后 clean；合入前用正式包包名再验注册；全仓搜索 new OpenFileRequest 命中数应保持为一。字段语义继续以官方对接文档为准，随 SDK 小版本核对注释与默认值。

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