Test\n\nWPS body test with a code block.\n\nts\nconst x = 1;\n

Test

鸿蒙应用接入 WPS Open SDK 后，一条看似简单的“打开文档”链路，实际包含注册、文件沙箱、编辑参数、关闭回传四个检查点。页面能拉起 WPS，不代表业务已经拿到编辑结果；文档能打开，也不代表水印、修订和功能开关都按预期生效。把这条链路按阶段拆开，是联调时最省时间的方式。

本文按一次完整的文档打开与回传过程，复盘 `WPSApi`、`OpenFileRequest`、`sendRequest` 和 `ResultData` 的关键用法，并给出可直接套用的检查清单。

## 一条链路，四个检查点

完整的调用顺序可以概括为：

1. `registerApp` 完成应用注册，确认返回 `ResultCode.OK`。
2. 把待打开文件放入本应用沙箱，得到可读路径。
3. 构造 `OpenFileRequest`，设置编辑模式、水印、修订和回传方式。
4. 用户关闭文档后，处理 `ResultData`，把结果拷贝到业务沙箱。

| 阶段 | 关键对象 | 主要检查 |
|------|----------|----------|
| 注册 | `WPSApi.registerApp` | 包名、凭据、HAR 批次 |
| 打开 | `OpenFileRequest` | 沙箱路径、`enableEdit` |
| 编辑 | 水印、修订、`extraOptions` | 能力边界是否生效 |
| 回传 | `ResultData` | URI/FD、业务沙箱转存 |

注册是前置条件。没有注册成功就调用 `sendRequest`，通常会直接抛异常，而不是进入正常的打开回调。因此接入层最好把注册封装成 Promise，并缓存进行中的请求，避免页面重复注册。

## 注册与打开

注册时使用应用凭据，并等待回调成功。若当前交付包需要激活序列号，可以在成功回调中调用 `setWpsFileToken`；不需要时跳过即可。注册失败后要清空缓存，让下一次操作可以重新尝试。

打开文档前，先把文件拷贝到本应用沙箱。直接使用外部选择器返回的路径，可能因为权限不足导致 WPS 无法读取。构造请求时，`enableEdit` 不设置或为 `false` 表示只读，需要编辑时必须显式设为 `true`。

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

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,
  };

  return WPSApi.sendRequest(request);
}
```

`wpsTransferType` 决定关闭时使用 URI 还是 FD 回传。`extraOptions` 只对显式赋值的属性生效，未赋值的项保持默认行为，不要为了统一配置把所有开关都写成 `false`。

## 编辑期控制

水印通过 `wpsWaterMarkParams` 配置，常用字段包括是否启用、水印文字、角度、颜色和字号。修订通过 `wpsRevisionParams` 配置，可以指定修订作者、是否进入修订模式、是否显示修订面板。

`extraOptions` 负责分享、云文档、另存为、打印、导出、复制粘贴等细粒度开关。若启用了不落地，部分敏感能力会被底层强制关闭，即使开关写成开启也不会生效。联调时应分别验证只读、可编辑、水印、修订和功能限制，不要一次打开所有参数。

## 关闭回传与文件清理

没有设置 `enableTransferFile` 或 `wpsTransferType` 时，`sendRequest` 在 WPS 拉起成功后就会返回，`Result.data` 为空。需要编辑结果时，必须开启回传，并等待用户关闭文档。

URI 模式下，`result.data.fileUri` 是 WPS 沙箱里的临时路径；FD 模式下关注 `transferFd`、`transferFileName` 和 `transferFileSize`。两种方式都不能直接作为业务长期文件，必须复制到业务沙箱。

拷贝完成前不要删除 WPS 临时文件。拷贝成功后，再按安全策略清理。对于用户取消、WPS 崩溃或业务超时，不能假设一定会收到回调，业务侧应有可观测的失败状态。

## 联调清单

1. 应用包名与凭据一致，注册只发生一次。
2. 待打开文件位于业务沙箱，路径可读。
3. `enableEdit` 与业务预期一致，只读和可编辑分别测试。
4. 水印、修订和 `extraOptions` 在真实文档中生效。
5. URI 和 FD 回传至少各验证一次。
6. 回传文件完成业务沙箱转存后再清理临时文件。
7. 取消、崩溃和超时都有日志与失败状态。

把注册、打开、编辑控制和回传转存拆成四段，每段都有明确的输入、输出和失败信息，联调就不会把时间消耗在反复猜测上。

---
> 基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。
> 官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT
> 技术交流 QQ 群：628436767 · 对接咨询：m_open_sdk@wps.cn