HarmonyOS WPS Open SDK：对接文档阅读路径与联调自查

在 HarmonyOS 工程里接入 WPS Open SDK，最稳妥的做法不是先在业务页堆 OpenFileRequest，而是先把官方对接文档当成「可检索的接口手册」：注册、打开、回传、错误码各有固定章节。联调卡住时，若能按文档字段对齐日志，再带着 Result.code、Bundle 与 HAR 批次去寻求支持，效率会明显高于复述「打不开文档」。本文按「文档怎么读 → 常见调用链对照 → 自查清单 → 提问材料」整理一版工程向说明，字段语义以官方对接文档为准。

一、文档在接入链路中的位置

典型接入顺序可以概括为：申请凭据与 HAR → 依赖集成 → WPSApi.registerApp →（按交付约定）setWpsFileToken → OpenFileRequest + WPSApi.sendRequest → 可选关窗回传处理。对接文档把这条链拆成准备、快速接入、注册、参数、错误码与注意事项等章节，阅读时建议按调用阶段跳转，而不是从头到尾通读一遍。

阶段	文档侧关注点	代码侧锚点
准备	凭据、HAR、Bundle 绑定	本地配置与 `oh-package.json5`
注册	`registerApp` 回调与失败码	`ResultCode.OK` / `1013`
打开	`OpenFileRequest` 参数表	`enableEdit`、路径沙箱
回传	Transfer 相关字段	`wpsTransferType`、`Result.data`
排错	错误码表与注意事项	`.then` / `.catch` 分流

官方对接文档入口：https://365.kdocs.cn/l/clQl5cek2NoT 。建议在仓库 README 或内部 Wiki 固定该链接，避免多人各自收藏过期副本。

二、按问题类型跳读文档

联调中的问题大多可归为四类，对应不同阅读路径：

注册失败或未注册异常

先看应用注册与错误码章节：参数为空常表现为 ResultCode.ERROR；凭据或包名不匹配常见 ERROR_CODE_AUTH_FAILURE（1013）；sendRequest 在注册成功前调用会抛异常。代码上要把「注册态」与「打开态」拆开日志。

能打开但不能编辑 / 参数不符合预期

对照打开文档参数表：enableEdit 未设或为 false 均为只读；系统选择器路径需先拷贝到应用沙箱。不要把参数问题误报成鉴权问题。

关窗后拿不到业务路径

阅读关闭回传相关说明：配置 wpsTransferType 后需等待用户关窗；fileUri / FD 属于 WPS 侧临时结果，须拷贝到本应用沙箱后再入库或上传。

能力开关与交付批次

extraOptions、水印等能力以文档中的参数表为准；HAR 批次与申请材料不一致时，先核对交付说明再改业务代码。

三、联调前用代码固化「文档检查点」

把文档里的硬约束落成可运行检查，能减少无效提问：

typescript 复制代码

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

let sdkReady = false;

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

export async function openAfterDocsCheck(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  needEdit: boolean
): Promise<void> {
  if (!sdkReady) {
    throw new Error('registerApp not OK --- see docs error codes');
  }
  const request = new OpenFileRequest(ctx, sandboxPath);
  if (needEdit) {
    request.enableEdit = true;
  }
  try {
    const result = await WPSApi.sendRequest(request);
    if (result.code !== ResultCode.OK) {
      console.error('sendRequest', result.code, result.msg);
      return;
    }
  } catch (e) {
    console.error('sendRequest exception', e);
  }
}

说明：上述封装对应文档中的「先注册后打开」与「必须处理回调」两条注意事项；支持沟通时直接贴 code / msg 与是否已 sdkReady。

四、提问前材料清单

无论走官方渠道还是团队内部协助，建议一次性准备：

运行时 bundleName 与申请归档是否一致。
HAR 文件名 / 交付日期。
registerApp 的 code 与 msg。
是否调用 setWpsFileToken（按交付约定）。
sendRequest 结果或异常栈。
设备上的 WPS 客户端版本。
复现步骤：冷启动 → 注册 → 打开哪一类文件。
已对照文档的哪一节、仍无法解释的现象。

材料齐全时，支持方可直接判断是凭据绑定、参数误用还是客户端环境问题，而不是反复索要截图。

五、团队内沉淀文档用法

建议在工程内维护一页「对接文档索引」：把官方章节标题映射到本仓库模块名与关键 Issue 标签。新人入职时先跑通 registerApp + 打开样例，再叠加回传与水印。发版评审可把「错误码是否按文档分流」「密钥是否脱敏」写成阻塞项。避免把对接文档全文粘进业务注释；应引用章节主题与官方 URL，减少副本漂移。

负面用例也有助于验证「读懂了文档」：空凭据、未就绪打开、非沙箱路径。若 UI 与日志表现符合文档预期，说明门禁与分流已落地。

六、小结

HarmonyOS 上的 WPS 二开，官方对接文档是接口事实源，协作渠道是补充。把阅读路径按注册 / 打开 / 回传 / 排错拆开，用代码固化检查点，提问时带齐 Bundle、HAR、错误码与复现步骤，联调成本会明显下降。字段语义以官方文档为准；示例仅作工程编排参考。完成基线后再进入专题能力，节奏更可控。

建议将就绪状态做成显式门禁，打开入口只在注册成功后可用；日志同时保留注册 code 与客户端版本。若同时提供预览与编辑，拆成两个打开封装并分别写验收用例。回传场景要单独验证「未配置回传」与「配置回传并完成拷贝」。发版合并前核对 libs/ 下 HAR 修改时间，防止错误回滚。把文档跳读表与提问材料清单同步进发布模板后，换人维护与远程协助都会更省事；真机验证时先确认客户端可独立打开同类文档，再对照 SDK 注册日志，能更快区分客户端问题与凭据问题。

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。

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