HarmonyOS 应用把 WPS Open SDK 接到业务主路径后，功能演示往往已经能打开文档，但上线前仍容易漏掉「包名与凭据是否一致」「注册成功才开放打开入口」「默认只读是否被误当成可编辑」「关窗回传是否完成沙箱拷贝」等工程细节。本文按 registerApp → OpenFileRequest / sendRequest → Result 处理的调用链，整理一份可直接贴进发布评审的联调检查清单，字段语义以官方对接文档为准。

一、上线检查在调用链中的位置

建议把检查分成四层，而不是临发版时凭感觉扫一眼：

1. 交付与身份：HAR 批次、appKey / appSecret、运行时 Bundle 名称是否与申请归档一致。
2. 注册门禁：启动阶段是否观察到 ResultCode.OK，业务是否在就绪之后才调用 sendRequest。
3. 打开参数：enableEdit、水印、回传开关等是否符合产品验收口径。
4. 结果闭环：成功 / 失败 / 异常三分流；开启回传时是否把 WPS 侧临时路径拷贝到本应用沙箱。

二、凭据、HAR 与 Bundle 核对

上线包与调试包若 Bundle 不同，必须分别申请或明确以哪套为准。发布评审至少核对：

• 运行时打印的 bundleName 与申请归档一致。
• 当前工程依赖的 wps_sdk.har 与凭据来自同一批交付。
• appSecret 未进入公开仓库与 Release 明文日志。
• 需要激活序列号的交付形态，已在注册成功回调中调用 setWpsFileToken，而不是写在 OpenFileRequest 的临时字段上。

接入凭据在 SDK 侧为本地校验；应用侧要保证输入完整、未截断。换包名后须重新走官方申请渠道，不能只改本地字符串。

三、注册门禁与最小封装

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

type ReadyState = 'idle' | 'registering' | 'ready' | 'failed';

let state: ReadyState = 'idle';
let lastError = '';

export function bootstrapWps(
  appKey: string,
  appSecret: string,
  fileToken?: string
): void {
  if (!appKey || !appSecret) {
    state = 'failed';
    lastError = 'empty credentials';
    return;
  }
  state = 'registering';
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (result: Result): void => {
      if (result.code !== ResultCode.OK) {
        state = 'failed';
        lastError = `${result.code}:${result.msg}`;
        return;
      }
      if (fileToken) {
        WPSApi.setWpsFileToken(fileToken);
      }
      state = 'ready';
    },
  });
}

export function canOpenDocument(): boolean {
  return state === 'ready';
}

检查要点：启动只注册一次；打开按钮绑定 canOpenDocument()；失败态展示 lastError 便于现场抓取。切勿在多个页面各自调用 registerApp 造成日志混乱。

四、打开参数与结果处理

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

async function openForRelease(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  needEdit: boolean,
  needTransfer: boolean
): Promise<void> {
  if (!canOpenDocument()) {
    throw new Error('WPS SDK not ready');
  }
  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('open failed', result.code, result.msg);
      return;
    }
    // 若开启回传：将 result.data.fileUri 拷贝到本应用沙箱后再入库/上传
  } catch (e) {
    console.error('sendRequest exception', e);
  }
}

参数侧清单：

• 编辑验收场景必须显式 enableEdit = true（未设或 false 均为只读）。
• 从系统选择器拿到的路径，先拷贝到应用沙箱再传入。
• 真机已安装与 SDK 交付匹配的 WPS 客户端。
• sendRequest 同时处理非 OK 与 catch（未注册等）。

回传侧清单：

• 需要关窗后继续上传时，确认已设 wpsTransferType。
• fileUri / FD 仅表示 WPS 侧临时结果，必须拷贝到本应用目录后再作为业务 filePath。
• 区分「拉起成功但未开回传」与「回传成功」两种语义，避免 UI 误报保存成功。

五、错误码分流与发布评审表

发布评审建议勾选：

1. Bundle / 凭据 / HAR 归档一致。
2. 启动日志可见一次 registerApp 成功。
3. 打开入口受就绪门禁保护。
4. 编辑 / 只读口径与 enableEdit 一致。
5. 回传场景已完成沙箱拷贝联调。
6. 崩溃上报过滤 appSecret 与完整序列号。
7. Release 包在目标机型完成一次端到端打开。

六、配置安全、回归范围与现场抓取

密钥按构建变体注入；CI 可打印 bundleName 做比对。回归至少覆盖：冷启动注册、只读打开、可编辑打开、（如有）回传落盘、注册失败重试。热更新或热重启 Ability 后，确认就绪状态仍可被业务正确读取，避免半就绪并发打开。

设备侧可先用系统能力确认样例 Office 文档可读，再交给 SDK，减少「路径问题」与「鉴权问题」的混淆。日志中同时保留注册 code 与客户端版本，远程协助时更高效。建议在测试包增加隐藏入口，一键导出：Bundle、HAR 标识、注册结果、最近一次 sendRequest code、是否配置回传。现场抓取比口头描述「打不开」更有用。

不要把水印、修订、extraOptions 与注册联调绑在同一轮变更里。注册与基础打开稳定后，再按专题叠加高级能力，排障边界更清晰。若上线包替换过 HAR，务必重新跑一遍身份层核对，避免历史批次残留在 libs/ 目录。

发布前还可做一次「负面用例」：故意传空 appSecret、故意在未就绪时点打开、故意传入非沙箱路径，确认 UI 与日志表现符合预期，而不是静默失败。负面用例通过，说明门禁与分流真正生效，而不是只在幸福路径上演示成功。

七、小结

上线前检查不是把对接文档条目再抄一遍，而是把身份、门禁、参数、闭环四层变成可勾选、可复现的工程动作。HarmonyOS 上的 WPS 二开只要 registerApp 与 sendRequest 边界清晰，编辑与回传等能力才站得住。把本清单固化进发布模板，能显著降低换人维护与周末热修的概率。完成基线后再进入水印与回传专题，节奏更可控；真机验证时先确认客户端可独立打开同类文档，再对照 SDK 注册日志，能更快区分客户端问题与凭据问题。

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