HarmonyOS WPS Open SDK 快速入门：HAR 装上就能打开文档吗

很多人拿到鸿蒙 WPS Open SDK 后的本能反应是：把 Demo 按钮抄进业务页。真机上却常卡在依赖、注册和路径三处。统一版的好消息是------专业版（ToB）与个人版（ToC）共用 WPSApi + OpenFileRequest，快速入门只学一套 API。差异落在 HAR / 凭据、是否 setWpsFileToken，以及少数字段是否生效。

本文按「半天能跑通」的目标写：依赖怎么装、注册怎么写、打开怎么验、哪里会分叉。

你要达成的最小闭环

@wps/wps_sdk 能 import
registerApp 回调 ResultCode.OK
真机只读打开一份沙箱内 docx
再开一次 enableEdit = true

水印、extraOptions、不落地、关窗回传都放到闭环之后再叠。一次堆满开关，ResultCode.ERROR 很难归因。

接入实操：依赖、注册、打开

HAR 与凭据

在 oh-package.json5：

json5 复制代码

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

把交付的 wps_sdk.har 放进 ./libs/，ohpm install。申请凭据时邮件注明包名与版本需求（专业版 / 个人版），凭据与 bundleName 绑定，不可混用。换 HAR 后务必 clean。

注册写成可 await

typescript 复制代码

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

function prepareWps(key: string, secret: string, sn?: string): Promise<void> {
  return new Promise((resolve, reject) => {
    WPSApi.registerApp(key, secret, {
      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}`));
          return;
        }
        // 个人版通常跳过；专业版在成功回调里一次设置
        if (!SdkConstants.isPersonalSdk() && sn) {
          WPSApi.setWpsFileToken(sn);
        }
        resolve();
      }
    });
  });
}

未注册成功就 sendRequest 会抛异常。冷启动 await prepareWps，打开按钮等就绪后再亮。Release 不要打印完整 secret。

沙箱打开

typescript 复制代码

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

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

export async function openDoc(
  ctx: common.UIAbilityContext,
  src: string,
  editable: boolean
): Promise<Result> {
  await prepareWps(APP_KEY, APP_SECRET, PRO_SN_OR_EMPTY);
  const path = toSandbox(ctx, src);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = editable;
  return WPSApi.sendRequest(req);
}

默认只读；显式 true 才可编辑。路径务必先落沙箱。需要关窗回传时再赋 wpsTransferType，与可编辑开关独立。

专业版 / 个人版：快速入门要记住的分叉

项	专业版（ToB）	个人版（ToC）
HAR / 凭据	匹配专业版	匹配个人版
注册	必须	必须
激活序列号	通常 `setWpsFileToken`	注册成功后一般不需要
不落地等	按文档生效	部分字段设置后不生效

用 SdkConstants.isPersonalSdk() 收在适配层，不要在每个页面写 if (isPro)。统一版解决的是接口一致，不是抹掉交付差异。

排错速查

现象	优先查
`sendRequest` 抛异常	是否等 `prepareWps` 完成
`1013`	key/secret/`bundleName`
泛化 ERROR	路径是否沙箱、Context
Release 才失败	clean；正式包包名

全仓搜索 new OpenFileRequest：快速入门阶段就该只有一处 Facade。产品下周要求「预览也要水印」时，扩展可选参数，不要再开平行 Helper。

把协作也写进 PR：页面不得直接 new OpenFileRequest；序列号与版本差异只进 prepare / 配置；联调清单固定为注册 → 只读 → 可编辑 → 策略 → 回传。坚持住这几条，快速入门不会在两周后变成「仓库里三套打开代码」。

从 Demo 到业务工程

Demo 适合证明「能打开」。业务工程要证明「可维护」。迁移时我建议只搬三样东西：依赖目录约定、prepareWps / openDoc、联调清单。不要搬页面布局，也不要把密钥写进布局参数。

若同一仓库要服务多种交付形态，用 product flavor 注入 APP_KEY、APP_SECRET、PRO_SN_OR_EMPTY，Facade 类保持一份。页面永远只看见 prepare / open。这样专业版与个人版切换时，diff 主要出现在配置，而不是出现在业务页。

真机联调日志建议固定一行：code、msg、是否 ready、路径是否沙箱、是否 enableEdit。比「打开失败」四个字有用得多。当后续叠 extraOptions 出现「改了没效果」时，先确认字段是否显式赋值，再确认当前 HAR / 凭据是否允许该能力（部分形态下菜单会被强制关闭）。

把快速入门当成工程纪律的起点：从今天起全仓只允许一处 new OpenFileRequest，新需求只扩可选参数。两周后再搜一次命中数，比写长接入说明更能证明「统一版真正落到了仓库」。多人协作时冻结平行 Helper；合入前用正式包包名再验注册。需要关窗回传时再开 wpsTransferType，与可编辑开关独立组合。

小结

鸿蒙 WPS Open SDK 快速入门的本质是：HAR 装对、注册等 OK、文件进沙箱、一套 OpenFileRequest。专业版与个人版共用 API，差异收在适配层。字段语义以官方对接文档为准；申请 HAR 与凭据时注明版本需求。

再补一段工程侧提醒：快速入门不是「抄完 Demo 就结束」，而是把依赖目录、注册出口、沙箱打开函数固化成团队约定。合入前用正式包包名验一次注册，真机各跑一次只读与可编辑；日志打全 code / msg。若产品临时要求预览水印或关窗回传，只扩 Facade 可选参数，不新开平行文件。这样两周后再搜 new OpenFileRequest，命中数仍然是一，才算真正入门成功。换 HAR 后 clean；不要在 Release 打印完整 appSecret；不要在 Request 上重复塞 wpsToken。把这些写进 PR 模板，新人上手成本会明显下降。路径务必先落沙箱；外部 URI 权限不足时常见泛化 ERROR。正式包与调试包包名不同时，凭据批次也要分开归档，避免「本地绿、上架红」。若一周后产品又加「预览也要水印」，仍然只改 openDoc 可选参数，并把联调用例补一行：只读带水印。这样快速入门阶段立下的 Facade 边界，才不会被临时需求冲垮。

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