HarmonyOS 应用要在端内打开 Office 文档，常见路径是集成 WPS Open SDK，以 HAR 形式接入 @wps/wps_sdk，通过单例 WPSApi 完成注册与打开。统一版交付后，对外调用模型保持不变：registerApp 成功后再 sendRequest，打开统一走 OpenFileRequest，结果落在 Result 与 ResultCode。差异主要体现在凭据形态是否需要激活序列号、以及部分策略字段在当前交付批次是否生效——这些以官方对接文档标注为准，而不是在业务层硬编码分支。本文按接入主线做概述：先看 SDK 在工程中的位置，再落到注册、打开、策略与回传，最后给出可复用封装与联调清单。

一、统一版在 HarmonyOS 工程中的位置

典型时序固定为：集成 HAR → 启动阶段 registerApp →（按凭据约定）可选 setWpsFileToken → 构造 OpenFileRequest → WPSApi.sendRequest 拉起 WPS →（若开启回传）关窗后 Promise 兑现 Result.data。

层级	职责	主要入口
依赖层	HAR、凭据、包名绑定	@wps/wps_sdk
接入层	应用注册、按需激活序列号	registerApp / setWpsFileToken
打开层	沙箱路径、只读/可编辑	OpenFileRequest.enableEdit
策略层	水印、修订、菜单、落地相关	wpsWaterMarkParams / extraOptions / enableLocalization
结果层	关窗后拿回文件	wpsTransferType / Result.data

概述阶段最容易踩的坑，是把「能打开」当成验收终点。工程上更稳的做法是：页面只依赖「注册是否就绪」与「打开函数」，能力按层叠加；不要为预览、编辑、带水印打开再复制三份请求构造逻辑。统一版的价值在于同一套类型与回调机制覆盖多种交付形态，减少「换 HAR 就要重写打开页」的维护成本。

官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT 。建议在工程 README 固定该链接，避免多人收藏过期副本。

二、对外模型：WPSApi 与调用链

对接文档约定 SDK 对外统一入口为单例 WPSApi。注册与打开都通过 sendRequest 投递不同类型的 Request，而不是分散的静态方法集合。理解这一点有助于迁移旧工程：只要 Request 类型与字段对齐，业务页改动可以控制在 bootstrap 与 open helper 两层。

调用链门禁如下：

阶段	条件	失败表现
注册前打开	未 registerApp 成功	sendRequest 抛异常
身份不匹配	Bundle 与凭据不一致	1013 / ERROR_CODE_AUTH_FAILURE
参数不完整	路径不可读或凭据空	ResultCode.ERROR
打开成功	code === OK	WPS 拉起，未必有 data

Result 四个字段在联调中应成对记录：requestType 区分注册还是打开；code 对照 ResultCode；msg 用于日志与用户提示；data 仅在关闭回传成功时有意义。未开回传时 OK 且 data 为空是正常态，不应弹「保存成功」误导用户。

三、注册门禁与按需 Token

registerApp 必须在 sendRequest 打开文档之前完成且回调为 ResultCode.OK。注册成功后，若当前 HAR 与凭据约定需要激活序列号，在成功回调里调用 setWpsFileToken，一次设置全局生效；不要在 OpenFileRequest 上重复挂载 Token 字段。是否注入序列号应依据交付说明与凭据形态，不要用包名猜测。

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

let wpsReady = false;

function ensureRegistered(
  appKey: string,
  appSecret: string,
  activationSn?: string
): Promise<void> {
  return new Promise((resolve, reject) => {
    if (wpsReady) {
      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}: ${result.msg ?? ''}`));
          return;
        }
        if (activationSn && activationSn.length > 0) {
          WPSApi.setWpsFileToken(activationSn);
        }
        wpsReady = true;
        resolve();
      },
    });
  });
}

冷启动可在 Ability 初始化阶段 await ensureRegistered；首页「打开文档」在 wpsReady 前禁用。Release 包不要打印完整 appSecret。换 HAR 或换构建变体后务必 clean，核对 bundleName 与申请凭据一致，否则会出现调试包正常、正式包 1013。

四、OpenFileRequest 能力分层

无论后续叠多少策略，打开请求都是同一个类型。常用字段职责如下：

字段	作用
构造参数 filePath	建议为本应用沙箱可读路径
enableEdit	true 可编辑；默认/false 只读
wpsWaterMarkParams	水印
wpsRevisionParams	修订
extraOptions	分享、打印、导出等菜单级开关
enableLocalization	是否允许文档在 WPS 侧落地缓存
wpsTransferType	关窗回传方式（URI / FD）

默认只读是能力语义，不是缺陷：未设或为 false 时以只读打开；只有显式 true 才是可编辑。预览入口与编辑入口应共用同一打开函数，只差布尔参数。

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

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

async function openDoc(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  editable: boolean
): Promise<Result> {
  const req = new OpenFileRequest(ctx, sandboxPath);
  req.enableEdit = editable;
  return WPSApi.sendRequest(req);
}

系统文件选择器返回的路径往往不能直接被 WPS 长期访问。联调时先把文件 copyFileSync 到 filesDir，再构造 OpenFileRequest，能显著减少「偶现打不开」类工单。策略字段是否在当前批次生效，以对接文档参数表为准；验收时应对照文档逐项勾选，而不是假设「传了就应该有 UI 变化」。

五、结果回传与 ResultCode 分流

关闭回传需要显式设置 wpsTransferType，并在 Promise resolve 后处理 Result.data。URI 回传时 fileUri 位于 WPS 沙箱，业务入库前必须拷贝到本应用目录；FD 回传时关注 transferFd 与伴随的文件名、大小字段。把临时 URI 直接当持久化路径，是概述类文档里最常见、也最容易在发版后被忽略的闭环漏项。

错误码处理建议固定顺序：依赖与 Bundle → 注册门禁 → 打开参数 → 回传拷贝。出现 1013 时暂停参数实验，先对齐申请材料与运行时包名打印值。打开抛异常与打开返回非 OK 是两类问题：前者多半是未注册成功，后者多半是路径、权限或客户端状态。

code / 现象	含义倾向	处理
1013	身份不匹配	对 Bundle、凭据、HAR 批次
ERROR	参数不完整	补凭据、路径
打开异常	未注册	修门禁
打开非 OK	路径/客户端	对照文档

六、工程封装与联调清单

建议拆成 WpsBootstrap（注册与就绪态）与 WpsOpenHelper（构造 Request、处理 Result），业务页只消费 sdkReady 与 openDocument。日志关键字统一为 registerApp、gate、open non-ok、open exception，便于从设备日志过滤周回归。

联调清单（概述版）：

字段	填写
HAR 文件名
Bundle 打印值
注册结果	OK / code:msg
Token	已设 / 本交付无需
只读打开	通过 / 失败
可编辑打开	通过 / 失败
回传落盘	未启用 / 通过

真机保留一次冷启动注册日志。远程协助时一次带齐：Bundle、HAR 交付日、注册 code/msg、打开结果或异常栈、是否已 setWpsFileToken、已对照文档哪一节。材料越完整，越少反复确认是否混用了凭据。

依赖写法：

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

执行 ohpm install 后全量编译，确认 import 来自 @wps/wps_sdk。Ability 启动注册、页面消费就绪态这一结构，应在评审纪要里写明负责人与文件路径，避免下一位同事再次把 registerApp 写回某个业务页的生命周期回调。

七、小结

HarmonyOS WPS Open SDK 统一版的核心，是把文档二开能力收在 WPSApi + OpenFileRequest + ResultCode 的可重复调用链上。接入概述不应停在「能打开」，而应明确注册门禁、沙箱路径、只读默认可编辑显式、策略字段按文档验收、回传开启则必须落盘拷贝。按本文分层理解后，后续专题（水印、extraOptions、不落地、关闭回传）都能在同一打开封装内增量叠加，而不必在每个页面分叉配置。

请将对接文档链接固定到工程文档，并在每次 HAR 变更后重跑必测项：注册 OK、只读打开、可编辑打开、（若启用）回传落盘。出现 1013 时优先对齐身份材料，再调业务参数。把联调清单贴进发布评审，比临发版口头确认更稳；远程协助同时附上 HAR 文件名与一次冷启动注册日志，通常能少问两轮。统一版让「同一套代码、多种交付形态」成为可能，工程纪律才是把可能性变成稳定体验的关键。

---

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