在 HarmonyOS 项目里接入 @wps/wps_sdk 之后，能力点会很快散开：注册、沙箱路径、只读与可编辑、水印、菜单开关、关窗回传。业务同学往往按「页面需求」各自加字段，联调时却对不上同一条调用链。本文把近期二开实践里反复出现的能力点收回到 WPSApi → OpenFileRequest → Result 主线上，方便周复盘与代码评审；字段语义以官方对接文档为准。

一、回顾在调用链中的位置

统一入口仍是单例 WPSApi。一条可验收的链路通常是：

registerApp 成功 →（按凭据约定可选）setWpsFileToken → 构造 OpenFileRequest → sendRequest → 用户关闭后读取 Result。

周回顾的价值，不是再列一遍参数名，而是确认工程里是否仍只有一处打开封装在演进这些字段。

二、依赖与注册：周复盘必查项

依赖名保持 @wps/wps_sdk，HAR 文件与 appKey / appSecret 必须来自同一申请批次，并与安装包 bundleName 一致。换包或换构建变体后务必 clean；否则会出现调试包正常、正式包 1013（ResultCode.ERROR_CODE_AUTH_FAILURE）。

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

let ready = false;

function prepare(appKey: string, appSecret: string, sn?: string): Promise<void> {
  return new Promise((resolve, reject) => {
    if (ready) {
      resolve();
      return;
    }
    WPSApi.registerApp(appKey, appSecret, {
      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 (sn && sn.length > 0) {
          WPSApi.setWpsFileToken(sn);
        }
        ready = true;
        resolve();
      },
    });
  });
}

序列号优先在注册成功回调里全局设置。迁移或周迭代时，删掉业务里对 request.wpsToken 的逐次赋值，避免双源。Release 日志不要打印完整 secret。

三、打开层：同一 OpenFileRequest，差异用参数表达

预览与编辑应共用一个函数，只差 enableEdit 与可选回传开关。路径建议 copyFileSync 到 filesDir 再打开；外部 URI 权限不足时，常直接落到泛化 ResultCode.ERROR。

import { common } from '@kit.AbilityKit';
import fs from '@ohos.file.fs';
import { TransferType } from '@wps/wps_sdk';

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

async function openDoc(
  ctx: common.UIAbilityContext,
  src: string,
  editable: boolean,
  withTransfer: boolean
): Promise<Result> {
  await prepare(APP_KEY, APP_SECRET, ACTIVATION_SN);
  const path = toSandbox(ctx, src);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = editable;
  if (withTransfer) {
    req.wpsTransferType = TransferType.TRANSFER_TYPE_URI;
  }
  return WPSApi.sendRequest(req);
}

可编辑与回传是两个独立开关：能编辑不意味着必须回传，回传也不强制可编辑。入口语义决定组合，不要在复制粘贴中写死「编辑=回传」。

四、策略层：水印、extraOptions 与落地相关字段

水印、修订、extraOptions、落地相关控制都挂在同一 OpenFileRequest 上。extraOptions 仅对显式赋值的字段生效；未赋值不要假设「默认全关」。部分字段按当前 HAR / 凭据形态生效——方案评审应先确认交付约定，再画菜单矩阵，否则会出现「改了开关却没变化」。

建议叠加顺序：注册 OK → 沙箱只读 → enableEdit = true → 水印 / 修订 → extraOptions → 落地相关字段（若约定支持）→ 关窗回传。一次堆满所有开关时，ResultCode.ERROR 很难归因。

五、结果层：关闭回传怎么验收

开启 URI 或 FD 回传后，用户关窗时 Promise resolve，Result.data 携带路径或描述符信息。验收时至少核对：code 是否 OK、业务关心的字段是否非空、沙箱侧是否能继续上传或归档。回传失败时把 code 与 msg 打全，比只打「打开失败」四个字有用。

FD 与 URI 模式字段不同，封装层应分支处理，并在注释里写清当前工程采用哪一种，避免同事按另一模式解析空字段。

六、Facade 与周复盘清单

页面只依赖 prepare / openDoc，构建变体注入 key、secret、可选 sn。审批附件、消息预览、本地导入等入口全部改调 Facade；换包评审把「是否还有第二份 new OpenFileRequest」列为必查项。

周复盘还可追加：正式包是否打印 secret、是否残留逐次 wpsToken、多模块是否并行长出平行打开封装。

七、小结

鸿蒙侧 WPS Open SDK 二开能力可以很多，但主线始终是同一套调用链。周回顾应确认：依赖与凭据对齐、注册成功后再打开、序列号收回全局、打开逻辑共用 OpenFileRequest、策略与回传按层叠加。把这些点写进 Facade 与联调表，比口头交接更不容易回退到散落实现。字段与错误码请以官方对接文档为准，随 SDK 版本核对后再合入。

实践里建议把「周复盘」做成固定节奏：周一扫依赖与凭据，周三跑正式包包名注册，周五用同一 Facade 回归只读、可编辑与回传。多模块并行接入时，迁移窗口内应冻结新增平行打开封装，统一走 Facade 合入，减少回退成本。新人上手时，与其先背参数表，不如先画清调用链再对照对接文档核对字段。预览与编辑入口共用 openDoc，仅差布尔与可选策略对象，可避免水印、回传字段在复制粘贴中丢失。合入前用正式包包名再跑一遍注册，确认不再出现仅 Release 才有的 1013。若团队有多入口并行接入文档能力，复盘清单里应额外盯「是否还有第二份构造打开请求」，这比争论「该不该加水印」更能缩短联调时间。

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