HarmonyOS WPS Open SDK 二开工程复盘:文档链路的五个关键节点

25 阅读7分钟

把 WPS Open SDK 接进 HarmonyOS 工程,最初看起来只是“注册一下、打开一个文件”。真正进入联调后,问题往往集中到另外几个地方:页面重复发起注册、调试包和正式包的凭据混用、文件路径权限不足、编辑参数组合互相覆盖、关闭回传后拿到一个不能长期使用的 WPS 沙箱路径。单看每个 API 都不复杂,但把它们串成一条稳定链路,需要工程上的分层和状态管理。

这篇复盘不再逐条罗列参数,而是从工程视角把文档能力拆成五个节点:SDK 就绪、文件进入业务沙箱、请求参数组合、编辑期能力边界、关闭回传与文件生命周期。每个节点都给出可复用的代码骨架和联调检查点,便于在真实项目中落地。

一、节点一:SDK 就绪状态

registerApp 是回调式接口,但业务页面通常希望用 Promise 或 async/await 组织流程。直接在每个页面里调用注册,会带来两个问题:并发时重复注册,失败后没有统一的重试入口。更稳妥的做法是把注册封装到单独的接入模块,并缓存进行中的 Promise。

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

let sdkReady: Promise<void> | null = null;

export function ensureSdkReady(
  appKey: string,
  appSecret: string,
  activationToken?: string
): Promise<void> {
  if (sdkReady) {
    return sdkReady;
  }

  sdkReady = new Promise<void>((resolve, reject) => {
    WPSApi.registerApp(appKey, appSecret, {
      onCallback: (result: Result): void => {
        if (result.code !== ResultCode.OK) {
          sdkReady = null;
          reject(new Error(`registerApp failed: ${result.code} ${result.msg}`));
          return;
        }

        if (!SdkConstants.isPersonalSdk() && activationToken) {
          WPSApi.setWpsFileToken(activationToken);
        }
        resolve();
      },
    });
  });

  return sdkReady;
}

这里把版本差异收在接入层:当前集成包需要激活序列号时,在注册成功回调中调用 setWpsFileToken;不需要时直接跳过。页面层只等待 ensureSdkReady(),不关心具体交付包。注册失败要清空缓存,否则一次失败会让后续调用一直复用被拒绝的 Promise。

联调时建议把注册结果和错误码单独打点,至少记录包名、HAR 批次、结果码和 key 的末几位。这样出现 1013 时,可以先核对应用身份,而不是在打开参数里反复尝试。

二、节点二:文件进入业务沙箱

OpenFileRequest 的第二个参数是本地文件路径。这个路径最好位于业务应用自己的沙箱目录,而不是系统文件选择器返回的外部路径。外部路径在部分设备或权限状态下可能无法被 WPS 读取,表现通常是打开失败,但错误信息并不一定直接指向权限。

工程上可以把“准备文件”做成独立步骤:

  1. 从业务下载、缓存或文件选择器取得源文件。
  2. 把文件拷贝到 context.filesDir 下的文档工作目录。
  3. 检查文件是否存在、大小是否大于 0、扩展名是否受支持。
  4. 把沙箱路径传给 OpenFileRequest,并在请求结束后按业务策略清理。

这一步看似简单,却能排除大量“同一个文件在 A 设备能打开、B 设备打不开”的问题。文件路径、文件权限和 WPS 客户端环境是三个不同维度,先保证业务侧路径稳定,后续才有可比性。

三、节点三:请求参数组合

请求参数建议集中在一个构建函数里,而不是散落在页面事件中。这样水印、修订、功能开关和回传方式可以一起审查,避免某个入口漏配。

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

export async function openDocument(
  context: common.UIAbilityContext,
  sandboxPath: string
): Promise<Result> {
  await ensureSdkReady(APP_KEY, APP_SECRET, ACTIVATION_TOKEN);

  const request = new OpenFileRequest(context, sandboxPath);
  request.enableEdit = true;
  request.enableLocalization = false;
  request.wpsTransferType = TransferType.URI;

  request.wpsWaterMarkParams = {
    Enable: true,
    WaterMaskText: '内部审阅',
    Angle: -30,
    FontColor: '#19000000',
    FontSize: 18,
  };

  request.wpsRevisionParams = {
    UserName: '文档审阅人',
    EnterReviseMode: true,
    ShowRevisionPanel: true,
  };

  request.extraOptions = {
    enableShare: false,
    enableCloud: false,
    enableSaveAs: false,
    enablePrint: false,
    enableExport: false,
  };

  return WPSApi.sendRequest(request);
}

enableEdit 默认为只读,需要编辑时必须显式设置为 true。wpsTransferType 决定关闭时使用 URI 还是 FD 回传。extraOptions 只对显式赋值的属性生效,未赋值的项保持 WPS 默认行为,因此不要为了“统一配置”把所有开关都写成 false,否则可能误伤正常能力。

如果启用了不落地,部分敏感能力会被底层强制关闭,即使 extraOptions 里写成开启也不会生效。参数组合完成后,建议在代码评审时专门检查一次“业务期望”和“实际生效”的差异。

四、节点四:编辑期能力边界

文档打开后,业务侧能控制的不是页面 UI,而是 WPS 内部的编辑能力。水印用于标识文档来源,修订用于保留修改痕迹,extraOptions 用于限制分享、云文档、另存为、打印、导出、复制粘贴等操作。它们共同构成编辑期的能力边界。

实际项目里可以把这些配置分成三组:

配置组主要参数关注点
展示标识wpsWaterMarkParams水印文字、角度、颜色、字号
修改痕迹wpsRevisionParams修订作者、修订模式、修订面板
功能限制extraOptions分享、云文档、另存为、打印、导出、复制粘贴

这三组参数不要在每个页面里重复手写。更合理的做法是由业务配置生成一个请求模板,页面只传入文件路径和业务上下文。这样后续新增入口时,不会出现某个页面忘记关分享、另一个页面忘记开修订的情况。

另外要区分“只读”和“功能限制”两件事。enableEdit=false 表示用户不能编辑;extraOptions 是在可编辑前提下限制某些操作。两者叠加时,应该先明确业务场景,再决定哪些开关需要显式设置。

五、节点五:关闭回传与文件生命周期

如果业务需要拿到编辑结果,必须设置 enableTransferFile 或 wpsTransferType。否则 sendRequest 在 WPS 拉起成功后就会返回,Result.data 为空,关闭文档时也不会再有业务回调。

import fs from '@ohos.file.fs';
import fileuri from '@ohos.file.fileuri';
import { common } from '@kit.AbilityKit';
import { Result, ResultCode } from '@wps/wps_sdk';

function copyWpsUriToBusiness(
  context: common.UIAbilityContext,
  wpsFileUri: string
): string | undefined {
  const source = fs.openSync(wpsFileUri, fs.OpenMode.READ_ONLY);
  if (!source.path) {
    return undefined;
  }

  const name = source.path.substring(source.path.lastIndexOf('/') + 1);
  const dir = `${context.filesDir}/wps_callback/${Date.now()}/`;
  fs.mkdirSync(dir, true);
  const target = dir + name;
  fs.copyFileSync(source.fd, target);
  return fileuri.getUriFromPath(target);
}

export function handleTransfer(
  context: common.UIAbilityContext,
  result: Result
): void {
  if (result.code !== ResultCode.OK || !result.data) {
    console.error('transfer failed', result.code, result.msg);
    return;
  }

  const wpsFileUri = result.data.fileUri;
  if (!wpsFileUri) {
    console.info('no transfer file');
    return;
  }

  const localUri = copyWpsUriToBusiness(context, wpsFileUri);
  if (!localUri) {
    console.error('copy to business sandbox failed');
    return;
  }

  // 先完成业务拷贝,再按安全策略清理 WPS 临时文件
  fs.unlink(wpsFileUri, (err) => {
    if (err) console.error('delete WPS temp file failed', err);
  });
}

URI 回传给的是 WPS 沙箱路径,不能直接作为业务长期路径;FD 回传则需要按块读取并关闭文件描述符。回传文件的生命周期应该由业务状态机管理:打开中、编辑中、已收到回调、已拷贝到业务沙箱、业务保存完成。只有“已拷贝”之后,才能认为业务真正持有了编辑结果。

不落地场景下,WPS 不应形成持久化缓存副本,但关闭回传时仍可能产生临时文件。业务侧应在拷贝成功后清理,并接受“异常退出可能没有回调”的现实,准备超时和补偿逻辑。

六、联调矩阵与上线复盘

上线前可以按下面这张矩阵做一次联调,而不是只测“能打开”:

场景检查点
首次启动注册只发生一次,失败后可重试
只读打开enableEdit 未设置时不可编辑
编辑打开enableEdit=true 后可修改并保存
水印修订水印文字、角度、修订面板符合预期
功能限制分享、打印、导出、复制粘贴符合边界
关闭回传URI/FD 与处理代码一致,业务沙箱有结果
异常退出取消、崩溃、超时均有可观测状态

工程复盘的价值不在于把所有参数都打开,而在于知道每个节点负责什么、失败时应该看哪里。注册层看应用身份,打开层看文件路径与编辑模式,编辑层看能力边界,回传层看沙箱转存和生命周期。把这条链路拆清楚,后续增加水印、限制导出或接入新的文档入口,都只是在既有骨架上扩展,而不是重新拼一套页面逻辑。


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