HarmonyOS WPS Open SDK 实践：二开能力周回顾如果团队已经跑通「能打开文档」，接下来一周最容易散的是

如果团队已经跑通「能打开文档」，接下来一周最容易散的是能力点：专业版（ToB）要不要 Token、个人版（ToC）哪些参数不生效、编辑和水印怎么叠、关窗回传怎么落盘。本文按统一版口径做一次周回顾——同一套 WPSApi / OpenFileRequest，把差异收口在初始化与参数表「是否生效」列，方便写进迭代回顾。

统一版回顾：一套 API，显式差异

统一版解决的是「两套习惯」：接口、参数模型、回调机制对齐；ToB / ToC 仍是不同 HAR 与凭据，申请时必须写清。开发侧用 SdkConstants.isPersonalSdk() 判断当前包形态，而不是猜测客户端包名。

主题	本周应记住的结论
注册	两端都必须 `registerApp` 成功后才能打开
Token	ToB 通常在回调里 `setWpsFileToken`；ToC 一般不需要
打开	沙箱路径 + 显式 `enableEdit` 等
高级能力	以文档「是否生效」列为准
排错	身份 → 注册 → 参数 → 回传

官方文档：365.kdocs.cn/l/clQl5cek2…

最小可运行骨架

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

let ready = false;

export function weeklyBootstrap(
  appKey: string,
  appSecret: string,
  proSn?: string
): void {
  WPSApi.registerApp(appKey, appSecret, {
    onCallback: (result: Result): void => {
      if (result.code !== ResultCode.OK) {
        ready = false;
        console.error(result.code, result.msg);
        return;
      }
      if (!SdkConstants.isPersonalSdk() && proSn) {
        WPSApi.setWpsFileToken(proSn);
      }
      ready = true;
    },
  });
}

export async function weeklyOpen(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  opts: { edit?: boolean; transfer?: boolean } = {}
): Promise<void> {
  if (!ready) {
    throw new Error('registerApp not OK');
  }
  const request = new OpenFileRequest(ctx, sandboxPath);
  if (opts.edit) {
    request.enableEdit = true;
  }
  if (opts.transfer) {
    request.wpsTransferType = TransferType.URI;
  }
  const result = await WPSApi.sendRequest(request);
  if (result.code !== ResultCode.OK) {
    console.error('open', result.code, result.msg);
  }
}

这段代码覆盖周回顾的三条纪律：就绪门禁、Token 全局化、打开参数显式化。业务页不要散落第二套注册逻辑。

能力分层：必测与选测

必测（两端）

冷启动注册 OK；未就绪打开被拦截。
沙箱样例可打开；选择器路径先拷贝。
只读默认 vs enableEdit = true。
失败日志能区分 1013、非 OK、未注册异常。

按交付选测

ToB：Token、不落地相关能力、水印与安全开关。
ToC：确认未误强制 Token；高级参数「设置不生效」不报成 Bug。
回传：URI/FD 拷贝到本应用沙箱后再作为业务 filePath。
extraOptions：分享 / 打印等按参数表验收。

误判	更可能的真相
「SDK 坏了」	Bundle / HAR / 凭据不一致
「不能编辑」	没设 `enableEdit`
「关窗没文件」	回传未落盘
「开关没用」	当前交付该参数不生效

提问模板（邮件 / 社群）

ToB 或 ToC + HAR 交付日
运行时 Bundle
registerApp 的 code / msg
sendRequest 结果或异常栈
是否已 setWpsFileToken（ToB）
已读文档哪一节仍无法解释

技术支持：m_open_sdk@wps.cn。完整 secret 不要发到群里。

周复盘建议落到仓库

把下列内容固定进 docs/wps-sdk.md：

当前 HAR 文件名与交付日
申请版本（ToB/ToC）与 Bundle
对接文档链接
就绪态 API 入口（bootstrap / open）
上一周回归勾选结果

下一次 HAR 升级时，只增量重跑必测项，而不是重新摸索。

排障顺序再强调一次

注册失败时不要先改水印；能注册不能打开时先查就绪态与沙箱路径；能打开行为不对时再查参数表。把顺序写进 Wiki，周回顾会少很多重复讨论。工程结构上继续坚持 Ability 启动注册、页面只消费就绪态，避免每个文档入口各自 registerApp。联调现场建议准备一份「本周对照」：HAR 文件名、Bundle 打印值、注册 code/msg、打开结果。四项齐全时，对照文档章节比反复猜测更快。若同时存在调试包与正式包，周回顾纪要里写清当前验收以哪套 Bundle 为准，避免 1013 被误判成偶现。水印与 extraOptions 建议在可编辑验收通过后再开，减少参数互相干扰；回传开启后务必验证业务侧拿到的是沙箱内最终路径，而不是 WPS 临时 URI。把这些约定写进 docs/wps-sdk.md 的「注意事项」小节，下一位同事接手时成本最低。

从 Demo 到评审：本周可交付物

除了代码能跑，周回顾最好留下三份可交付物，方便下周接手的人：

docs/wps-sdk.md：HAR 文件名、交付日、ToB/ToC、Bundle、对接文档链接。
就绪态封装：weeklyBootstrap / weeklyOpen（或等价命名）的仓库路径。
一次真机日志包：冷启动注册 OK、只读打开、可编辑打开；若启用回传再加关窗落盘。

有了这三份材料，邮件协助时不用从「我们接了 SDK」重新讲起。若本周还在排查 1013，优先停掉业务参数实验，先把身份三件套（Bundle、凭据、HAR）对齐；身份不稳时叠加水印或 extraOptions 只会制造噪声。ToC 场景若发现「设了不生效」，先打开对接文档参数表确认，再决定是否改产品预期。ToB 场景把 Token 留在注册回调，打开页保持干净，后续加回传时也不会和序列号逻辑缠在一起。

把「能力叠加顺序」写进迭代看板：注册 → 只读打开 → 可编辑 → 水印/开关 → 回传。每一列对应一个验收勾选，周会只看未勾选项，讨论会短很多。仓库里用一次 PR 描述贴上勾选表，比聊天记录更适合审计。

小结

周回顾的价值不是罗列卖点，而是把统一版接入收成可执行纪律：身份对齐、注册门禁、Token 收口、参数显式、回传落盘、日志分流。ToB / ToC 差异留在 bootstrap 与参数生效列，业务打开页尽量一套代码。做完上述勾选，团队对「二开能力全景」会有共同语言，后续专题深挖也有稳定底座。下一次 HAR 升级时，打开本文清单增量重跑即可，不必重新发明接入步骤。

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。官方对接文档：365.kdocs.cn/l/clQl5cek2… 技术交流 QQ 群：628436767