HarmonyOS WPS Open SDK：从 HAR 集成到打开文档的快速接入

less_12138

616人浏览 · 2026-07-30 09:10:20

less_12138 · 2026-07-30 09:10:20 发布

在 HarmonyOS 应用里接入文档能力，目标通常很明确：依赖装上、注册成功、真机能打开一份 Word。WPS Open SDK 以 HAR 交付，对外入口是单例 WPSApi，打开统一走 OpenFileRequest。本文按「依赖 → 注册 → 沙箱打开 → 排错 → 封装」写一版快速接入说明，帮你把官方快速接入示例落到工程里；字段语义以官方对接文档为准。

一、快速接入链路在工程里对应什么

对接文档把基础链路概括为：申请凭据与 HAR → 集成依赖 → registerApp →（按凭据约定）可选 setWpsFileToken → 构造 OpenFileRequest → sendRequest。工程落地时建议把状态拆开，而不是堆在一个按钮回调里。

阶段	关键动作	就绪标志
依赖	`libs/wps_sdk.har` + `ohpm install`	能 import `@wps/wps_sdk`
注册	`WPSApi.registerApp`	回调 `ResultCode.OK`
授权补充	可选 `setWpsFileToken`	按当前 HAR / 凭据约定
打开	沙箱路径 + `OpenFileRequest`	`sendRequest` 成功拉起 WPS

UI 只在注册成功后再启用「打开文档」。注册未完成就 sendRequest 会抛异常，这是接口硬约束，不是业务层「打开失败」。

二、HAR 依赖怎么装进工程

在 oh-package.json5 声明本地 HAR：

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

将交付的 wps_sdk.har 放入 ./libs/，执行 ohpm install。换 HAR 批次后务必 clean 再编译，否则旧 native 产物会让「明明换了包仍鉴权失败」的判断失真。

导入保持与文档一致：

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

调试包与上架包若 bundleName 不同，凭据通常要分别申请或明确以哪套为准。打包脚本建议打印一次包名，和申请材料并排归档。

三、registerApp：先就绪，再打开

对接文档要求：registerApp 回调未到 ResultCode.OK 之前调用 sendRequest 会抛异常。建议把回调收成可 await 的单出口，并在成功后按需注入激活序列号。

let wpsReady = false;

function ensureRegistered(
  appKey: string,
  appSecret: string,
  activationSn?: string
): Promise<void> {
  return new Promise((resolve, reject) => {
    if (wpsReady) {
      resolve();
      return;
    }
    WPSApi.registerApp(appKey, appSecret, {
      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}: ${result.msg ?? ''}`));
          return;
        }
        if (activationSn && activationSn.length > 0) {
          WPSApi.setWpsFileToken(activationSn);
        }
        wpsReady = true;
        resolve();
      }
    });
  });
}

冷启动可在 Ability 初始化阶段 await ensureRegistered。Release 不要打印完整 appSecret。是否调用 setWpsFileToken 由构建配置决定：需要序列号的变体传真实值，不需要的变体传空即可跳过。

四、OpenFileRequest：沙箱路径 + 只读/可编辑

路径侧建议先把选择器文件拷到应用沙箱，再传给 OpenFileRequest。直接传外部 URI 时，权限不足常落到泛化 ResultCode.ERROR。

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

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

async function openDocument(
  ctx: common.UIAbilityContext,
  src: string,
  editable: boolean
): Promise<Result> {
  await ensureRegistered(APP_KEY, APP_SECRET, ACTIVATION_SN_OR_EMPTY);
  const path = toSandbox(ctx, src);
  const request = new OpenFileRequest(ctx, path);
  request.enableEdit = editable; // 默认/false 只读；true 可编辑
  return WPSApi.sendRequest(request);
}

字段	快速接入常用取值
构造参数路径	本应用沙箱可读路径
`enableEdit`	预览 `false`；编辑 `true`
`wpsTransferType`	需要关窗回传时再开

预览与编辑共用同一打开函数，只差布尔参数，避免两套 Helper。回传与可编辑是独立开关，按入口语义组合。

五、最小联调顺序与错误码

推荐顺序：依赖可 import → 注册成功 → 沙箱只读打开 → 可编辑 →（可选）回传。一次堆满水印、extraOptions、落地相关字段，出了 ResultCode.ERROR 很难归因。

现象	优先排查
`sendRequest` 抛异常	`registerApp` 尚未成功
`1013`（`ERROR_CODE_AUTH_FAILURE`）	appKey/appSecret、包名与申请是否一致
打开失败、参数不完整	路径是否为空、Context 是否有效
换 HAR 后行为异常	是否 clean；正式包 `bundleName`

联调日志建议同时打出 code 与 msg。调试包正常、正式包 1013，根因经常是正式包名与申请凭据不一致。

六、可复用的两入口封装

把「注册就绪」与「打开文档」拆成稳定 API，页面只调用它们：

export class WpsQuickFacade {
  private ready = false;

  async prepare(appKey: string, appSecret: string, sn?: string): Promise<void> {
    if (this.ready) {
      return;
    }
    await ensureRegistered(appKey, appSecret, sn);
    this.ready = true;
  }

  async open(
    ctx: common.UIAbilityContext,
    sandboxPath: string,
    enableEdit: boolean
  ): Promise<Result> {
    if (!this.ready) {
      throw new Error('call prepare first');
    }
    const req = new OpenFileRequest(ctx, sandboxPath);
    req.enableEdit = enableEdit;
    return WPSApi.sendRequest(req);
  }
}

后续要加水印或关窗回传，扩展 open 的可选参数即可，不要在多个页面复制 new OpenFileRequest。

上线前再扫一遍：全仓 new OpenFileRequest 是否只剩一处、是否还在 Request 上逐次塞 wpsToken、Release 是否打印完整 secret、正式包包名与申请凭据是否一致。把这些写进 PR 模板，比口头说「已经接好了」更可靠。

快速接入阶段刻意不做的事同样重要：不要一次打开就写满水印、修订、extraOptions 与落地相关字段；不要为预览与编辑复制两套请求构造；不要在页面点击回调里直接 registerApp。能力按层叠加，失败才好归因。真机联调时建议固定日志格式：code、msg、当前是否 wpsReady、路径是否落在 filesDir 前缀下、本次是否赋值 enableEdit。这样排查「打不开」时，至少能分清是注册问题、路径问题还是策略问题。

若团队里已有 Demo 工程，迁移业务工程时优先搬 Facade，而不是搬按钮事件。Demo 常把注册与打开写在同一页，方便演示；业务侧冷启动连点、多页面重复注册、密钥散落会立刻出现。状态上至少区分依赖可 import、注册 OK、业务打开成功三层，UI 只在注册成功后启用打开入口。换 HAR 或换 flavor 后务必 clean，核对 bundleName 与申请材料一致，否则会出现调试包正常、正式包 1013。把这些节奏坚持几周，打开封装通常会从「多处拷贝」收敛到「一处 Facade」，联调时间也会从猜原因变成对表排查。字段语义仍以官方对接文档为准。

七、小结

鸿蒙侧 WPS Open SDK 的快速接入，可以压成四步：装好 HAR、等 registerApp 成功、文件进沙箱、用 OpenFileRequest 打开。工程上用 Facade 收敛调用，用联调顺序控制变量，比一次写满参数更稳。字段与错误码请以官方对接文档为准，随 SDK 版本核对。