在 HarmonyOS 工程里接入 WPS Open SDK，能力点分散在注册、打开参数、水印、功能开关与关闭回传等多个章节。日常联调往往只盯住当前症状，容易忽略整条调用链的先后顺序。本文把近期高频能力收成一张「联调地图」：先固定 WPSApi.registerApp →（按需）setWpsFileToken → OpenFileRequest + sendRequest，再按参数表核对编辑、回传与排错分流。字段语义以官方对接文档为准，便于写进团队 Wiki 或发布评审模板。

一、主调用链：能力落在哪里

建议始终按阶段阅读文档与代码，而不是按页面功能零散搜索：

1. 交付与身份：HAR、appKey / appSecret、运行时 Bundle 一致。
2. 注册门禁：回调 ResultCode.OK 之前禁止 sendRequest。
3. Token（按交付需要）：在注册成功回调中 setWpsFileToken，勿写到 Request 临时字段。
4. 打开参数：路径入沙箱；enableEdit、水印、extraOptions、回传开关按验收配置。
5. 结果处理：成功 / 非 OK / 异常三分流；回传 URI/FD 须拷贝到本应用沙箱。

官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT

二、注册与 Token：所有能力的底座

未注册成功就打开，Promise 会抛异常——这与「打开返回非 OK」不是一类问题。工程上建议把就绪态做成全局标志，打开按钮绑定该标志。

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

let ready = false;
let lastReg = '';

export function bootstrapSdk(
  appKey: string,
  appSecret: string,
  fileToken?: string
): void {
  if (!appKey || !appSecret) {
    ready = false;
    lastReg = 'empty credentials';
    return;
  }
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (result: Result): void => {
      if (result.code !== ResultCode.OK) {
        ready = false;
        lastReg = `${result.code}:${result.msg}`;
        console.error('registerApp', lastReg);
        return;
      }
      if (fileToken) {
        WPSApi.setWpsFileToken(fileToken);
      }
      ready = true;
      lastReg = 'OK';
    },
  });
}

export async function openWithRecap(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  needEdit: boolean,
  needTransfer: boolean
): Promise<void> {
  if (!ready) {
    throw new Error(`sdk not ready: ${lastReg}`);
  }
  const request = new OpenFileRequest(ctx, sandboxPath);
  if (needEdit) {
    request.enableEdit = true;
  }
  if (needTransfer) {
    request.wpsTransferType = TransferType.URI;
  }
  try {
    const result = await WPSApi.sendRequest(request);
    if (result.code !== ResultCode.OK) {
      console.error('sendRequest', result.code, result.msg);
      return;
    }
    // 若开启回传：从 result.data 取临时路径后拷贝到本应用沙箱
  } catch (e) {
    console.error('sendRequest exception', e);
  }
}

说明：fileToken 用可选参数表达「有则设置」；enableEdit 缺省为只读；回传用 TransferType.URI 示例，实际按产品选择 URI 或 FD。不要给 request.wpsToken 赋值。

三、打开侧能力速查

周回顾里最常被问到的打开参数，可按下表对照（完整表见对接文档）：

能力叠加顺序建议：先保证注册 OK + 能打开只读样例 → 再开编辑 → 再加水印 / 开关 → 最后开回传。不要在注册失败时优先调 extraOptions。

四、错误码与分流习惯

日志关键字建议固定：registerApp、sendRequest、gate、open non-ok、open exception，方便从设备日志过滤周回归结果。

五、发布前一周复盘清单

1. HAR 路径与 ohpm install 无漂移。
2. 运行时 Bundle 与申请归档一致。
3. 冷启动能看到 ResultCode.OK。
4. 需要序列号时已调用 setWpsFileToken。
5. 只读 / 可编辑各验一次。
6. 若启用回传：关窗后业务拿到沙箱内最终路径。
7. 1013 与未注册异常有独立日志，不混为一谈。
8. 文档链接写入 README：https://365.kdocs.cn/l/clQl5cek2NoT

把清单贴进发布评审，比临发版口头确认更稳。调试包与正式包 Bundle 不同时，必须分开核对申请材料。

六、工程结构建议

SDK 相关代码可收拢为 WpsBootstrap（注册 / Token / 就绪态）与 WpsOpenHelper（构造 Request / 处理 Result）。业务页只依赖「是否就绪」和「打开某路径」。凭据与序列号走本地安全配置或构建注入，避免进入公开仓库。HAR 文件名与交付日写进 docs/wps-sdk.md，和对接文档链接并列，周回顾时直接打开该页勾选。

七、小结与下周增量建议

二开能力再多，底座仍是注册门禁与身份对齐；打开侧用显式参数表达产品意图，回传侧完成落盘，排错按身份 → 注册 → 参数 → 回传顺序推进。用本文地图做周复盘，可以把零散 Demo 经验收成可复用的工程习惯。后续无论扩展编辑验收、功能开关还是关窗闭环，都应建立在稳定的 ResultCode.OK 之上。

若本周只完成了「能打开」，下周增量建议按固定节奏加：先把可编辑验收跑稳，再配置水印文案与位置，然后按产品需要打开 extraOptions 中的分享或打印等项，最后才启用关闭回传并完成沙箱拷贝。每加一层能力，保留一次成功日志与一次失败日志对照，比一次性堆满参数更容易定位。HAR 若有新批次，先只替换依赖并重跑注册与只读打开，确认身份无回归后再恢复高级参数。团队内把 Bundle、HAR 文件名、注册结果三列做成共享表格，远程协助时粘贴这三列即可减少来回确认。把对接文档入口写进 README 与内部 Wiki，避免每人收藏不同版本的链接副本。

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