把 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 读取,表现通常是打开失败,但错误信息并不一定直接指向权限。
工程上可以把“准备文件”做成独立步骤:
- 从业务下载、缓存或文件选择器取得源文件。
- 把文件拷贝到
context.filesDir下的文档工作目录。 - 检查文件是否存在、大小是否大于 0、扩展名是否受支持。
- 把沙箱路径传给
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…