鸿蒙应用集成 WPS Open SDK 时，工程团队常把「看文档」当成上线前的最后一环，结果在联调阶段才发现：注册时序、沙箱路径、回传字段各人对各人的理解。厂商对接文档并不是 API 列表的堆砌，而是一套按调用链组织的知识地图——先弄清 WPSApi 单例入口，再按章节对照 RegisterAppRequest 与 OpenFileRequest 的字段语义，才能把排错成本压到可控范围。本文给出一份可落地的阅读路径与联调自查表，并附 TypeScript 示例；字段含义以官方对接文档为准。

一、对接文档在工程里的角色

WPS Open SDK 鸿蒙版以 HAR 交付，对外统一为 WPSApi.sendRequest(Request)。文档按「申请凭据 → 注册 → 打开 → 策略字段 → 回传 → 错误码」展开，与运行时调用顺序一致。研发分工建议：

角色	建议精读章节	产出物
架构 / 负责人	能力概览、HAR 差异说明	接入时序图、Facade 边界
业务开发	OpenFileRequest 参数、示例代码	openDoc Facade
测试 / 驻场	ResultCode、常见异常	联调用例与日志模板

不要把文档当「查表手册」逐页翻；按里程碑阅读：集成 HAR 当天读注册章，首屏打开当天读 OpenFileRequest 章，上线前读错误码与回传章。

二、建议的阅读顺序

对接文档 v1.x 推荐按以下五步走，每步对应可验证的里程碑：

1. HAR 集成与凭据：确认 bundleName、AppKey/AppSecret 与当前交付包一致；记录文档中的申请字段，避免上线后追 1013。
2. registerApp：理解 RegisterAppRequest 须在打开前完成；冷启动 await 注册，按钮侧检查 wpsReady。
3. OpenFileRequest 构造：enableEdit 默认只读；沙箱路径须在 filesDir 下；策略字段（水印、extraOptions）在最小打开通过后叠加。
4. 关闭回传：未配置 wpsTransferType 时，OK 且无 data 合法；开启回传后再读 Result.data 并拷贝到本应用沙箱。
5. ResultCode 表：reject（未注册）、1013（鉴权）、ERROR（参数/路径）分开归因，日志带 stage。

申请凭据 → 集成 HAR → registerApp → copyToSandbox → OpenFileRequest → sendRequest → Result

三、关键章节与代码映射

文档中的示例代码应收敛进项目 Facade，而不是散落在页面。推荐映射关系：

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

/** 构建脚本注入：当前 HAR 是否在注册后需要 setWpsFileToken */
declare const BUILD_NEEDS_ACTIVATION_SN: boolean;

let wpsReady = false;

export async function ensureRegistered(ctx: common.UIAbilityContext): Promise<void> {
  if (wpsReady) return;
  const r = await WPSApi.sendRequest(
    new RegisterAppRequest(ctx, APP_KEY, APP_SECRET)
  );
  if (r.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
    throw new Error(`auth 1013: ${r.msg}`);
  }
  if (r.code !== ResultCode.OK) {
    throw new Error(`register failed: ${r.code}`);
  }
  if (BUILD_NEEDS_ACTIVATION_SN && ACTIVATION_SN) {
    WPSApi.setWpsFileToken(ACTIVATION_SN);
  }
  wpsReady = true;
}

打开链路对应文档「打开文档」章：

export async function openDoc(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  editable: boolean
): Promise<void> {
  await ensureRegistered(ctx);
  const req = new OpenFileRequest(ctx, sandboxPath);
  req.enableEdit = editable;
  const r = await WPSApi.sendRequest(req);
  if (r.code !== ResultCode.OK) {
    throw new Error(`open ${r.code} ${r.msg}`);
  }
}

全仓搜索 new OpenFileRequest 命中数应为 1；文档换版时先 diff Facade，再 diff 业务页。

四、联调自查清单

上线前可用下表做静态检查与真机走查：

检查项	通过标准	文档章节
注册时序	仅 bootstrap 调用 RegisterAppRequest	注册章节
路径	打开前文件在 filesDir 可读	打开参数章节
模式	编辑入口 enableEdit=true	enableEdit 说明
回传	未开启时不假设 data 有值	关闭回传章节
日志	含 stage/code/msg，无完整 secret	错误码章节

真机建议保留三段基线日志：register OK、open-read OK、open-edit OK，与文档示例对照，减少「文档写了但工程没落地」的争议。

五、日志与错误码归因

文档错误码章应贴在 Wiki 侧边栏。排错顺序：

• reject：未注册或注册未完成 → 查 ensureRegistered 与冷启动时序。
• 1013：bundleName 与凭据不匹配 → 对照申请邮件与当前 flavor。
• ERROR：沙箱路径、enableEdit、文件是否存在 → 先 copy 再打开。
• OK 无 data：未开回传 → 产品文案勿写「上传成功」。

export function logWps(stage: string, code: number, msg?: string): void {
  console.info(`[wps] stage=${stage} code=${code} msg=${msg ?? ''}`);
}

驻场导出日志时带上 stage，比截图弹窗更快对齐文档条目。

六、文档迭代与版本对齐

SDK 发版时同步三件事：HAR 版本号、对接文档 revision、应用内 registerApp 行为是否变化。建议在 CHANGELOG 记录「文档某章节字段默认值变更」，Code Review 对照文档 diff。若文档标注某字段「当前 HAR 不生效」，Facade 里用构建开关屏蔽，避免测试环境误配。

集成测试可维护「文档用例 ID → 自动化脚本」映射，例如 DOC-REG-01 对应注册失败分支，DOC-OPEN-02 对应只读打开。这样文档更新后，用例列表即回归范围。

驻场联调时，建议把文档「常见注意事项」抄进内部 runbook，并补充本项目 flavor 的 Key 注入方式。文档示例里的常量名可与仓库不一致，但调用顺序必须一致：sendRequest 之前完成注册，打开之前完成沙箱拷贝。若多模块依赖 SDK，在根 build-profile 统一声明 HAR 版本，避免子模块各自集成导致符号冲突。

Code Review 可增问三项：是否新增第二处 RegisterAppRequest；是否在 UI 层直接改 OpenFileRequest 字段；错误分支是否打印 code 而非笼统 Toast。三者都能在对照文档时快速定位。

七、小结

厂商对接文档的价值在于把 WPSApi 调用链讲清楚，而不是替代工程纪律。按「凭据 → 注册 → 沙箱 → 打开 → 回传 → 错误码」顺序阅读，并把示例收敛进 Facade，能显著降低联调阶段的理解偏差。把本文自查表并入 PR 模板，比口头同步「你看一下文档第三章」更可靠。

---

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