HarmonyOS WPS Open SDK：打开时配置水印与修订模式

在 HarmonyOS 应用接入 @wps/wps_sdk 后，只读/可编辑往往先跑通，下一步产品会要求「预览带水印」或「以修订模式打开」。对接文档把这两类能力挂在 OpenFileRequest 上：wpsWaterMarkParams（WaterMark）与 wpsRevisionParams（Revision）。本文按调用链说明字段语义、叠加顺序与封装写法，细节以官方对接文档为准。

一、策略层在打开链路中的位置

典型时序：registerApp 成功 → 文件进沙箱 → new OpenFileRequest → 写入 enableEdit →（可选）水印 / 修订 → sendRequest。

层级	能力	入口
接入	注册、可选序列号	`registerApp` / `setWpsFileToken`
打开	拉起、只读/可编辑	`enableEdit`
策略	水印、修订	`wpsWaterMarkParams` / `wpsRevisionParams`
结果	关窗回传	`wpsTransferType`

水印与修订属于策略层，不要和「能否打开」绑在同一个布尔里。联调建议：注册 → 沙箱只读 → 可编辑 → 再叠水印或修订 → 最后回传。一次写满所有开关时，ResultCode.ERROR 很难归因。

二、WaterMark 字段语义

类型：WaterMark，赋给 request.wpsWaterMarkParams。

属性	说明
`Enable`	是否启用水印
`WaterMaskText`	水印文字
`Angle`	旋转角度
`FontColor`	颜色（可含透明度），如 `"#19000000"`
`FontSize`	字号

常见误判：只 new 了对象却没设 Enable = true，或文字为空却期望看见水印。封装时应显式写完再赋值给 Request。

typescript 复制代码

import { WaterMark, OpenFileRequest } from '@wps/wps_sdk';

function applyWatermark(req: OpenFileRequest, text: string): void {
  const wm = new WaterMark();
  wm.Enable = true;
  wm.WaterMaskText = text;
  wm.Angle = -30;
  wm.FontColor = '#19000000';
  wm.FontSize = 24;
  req.wpsWaterMarkParams = wm;
}

水印可与只读同时存在：预览场景不必强行 enableEdit = true。

三、Revision 字段语义

类型：Revision，赋给 request.wpsRevisionParams。

属性	说明
`UserName`	修订作者名称
`EnterReviseMode`	是否以修订模式打开
`ShowRevisionPanel`	是否显示修订面板
`EnterRevisionSilent`	是否静默进入（不弹提示）

修订模式通常配合可编辑使用。若 enableEdit 仍为只读，用户无法有效产生修订痕迹。EnterRevisionSilent 适合减少打扰，但仍要在联调日志里打出是否进入修订。

typescript 复制代码

import { Revision } from '@wps/wps_sdk';

function applyRevision(req: OpenFileRequest, user: string, silent: boolean): void {
  const rev = new Revision();
  rev.UserName = user;
  rev.EnterReviseMode = true;
  rev.ShowRevisionPanel = true;
  rev.EnterRevisionSilent = silent;
  req.wpsRevisionParams = rev;
}

四、注册就绪与路径前提

未注册成功就 sendRequest 会抛异常，此时讨论水印无效。把注册收成可 await 的准备；换 HAR 或换正式包包名后 clean，再验注册。路径建议先拷到沙箱：外部 URI 权限不足时常见泛化 ERROR，容易被误判成「水印没生效」。

typescript 复制代码

let ready = false;

export function prepareWps(key: string, secret: string): Promise<void> {
  return new Promise((resolve, reject) => {
    if (ready) {
      resolve();
      return;
    }
    WPSApi.registerApp(key, secret, {
      onCallback: (result: Result): void => {
        if (result.code !== ResultCode.OK) {
          reject(new Error(`register ${result.code}`));
          return;
        }
        ready = true;
        resolve();
      },
    });
  });
}

需要激活序列号时，在注册成功回调里按凭据约定一次性设置，不要在每次 Request 上重复塞 Token。

五、可复用打开封装

把模式、水印、修订做成可选参数，页面不直接 new OpenFileRequest。

typescript 复制代码

export type OpenMode = 'preview' | 'edit';

export interface OpenPolicy {
  watermarkText?: string;
  revisionUser?: string;
  revisionSilent?: boolean;
}

export async function openDoc(
  ctx: UIAbilityContext,
  src: string,
  mode: OpenMode,
  policy: OpenPolicy = {}
): Promise<Result> {
  await prepareWps(APP_KEY, APP_SECRET);
  const path = copyToSandbox(ctx, src);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = mode === 'edit';
  if (policy.watermarkText) {
    applyWatermark(req, policy.watermarkText);
  }
  if (policy.revisionUser) {
    applyRevision(req, policy.revisionUser, !!policy.revisionSilent);
  }
  return WPSApi.sendRequest(req);
}

产品临时加「预览也要水印」，只扩 policy，不新开平行 Helper。关窗回传仍用独立字段，与水印/修订解耦。

六、联调表与日志

现象	优先查
抛异常	是否等注册完成
`1013`	凭据 / 正式包包名 / clean
无水印	`Enable`、文字、是否赋给 Request
无修订	`EnterReviseMode`、是否可编辑
泛化 ERROR	路径是否沙箱

日志固定：code / msg / ready / 沙箱 / enableEdit / 是否带水印 / 是否进修订。全仓 new OpenFileRequest 命中保持一处。

七、小结与工程落地建议

HarmonyOS 上 WPS Open SDK 的水印与修订，是打开策略层能力：在 enableEdit 跑绿后再叠 WaterMark / Revision。字段必须显式赋值；封装用可选策略对象收口。路径进沙箱、注册先就绪、回传另算一层。字段语义以官方对接文档为准。

接入评审建议逐项确认：当前 HAR 批次与包名是否匹配、沙箱目录约定是否统一、策略是否全部走 Facade、正式包与调试包的凭据是否分开归档。缺一环容易出现「本地绿、上架红」。把「先模式后策略」写进联调清单后，联调会从猜原因变成对表排查。换 HAR 后务必 clean 再装；Release 包不要打印完整 secret；需要序列号时按凭据约定在注册成功回调里一次性设置，避免在每次 Request 上重复塞 Token。

真机验收可拆成两条固定用例：其一「只读预览 + 水印」，其二「可编辑 + 修订（含静默开关各测一次）」。两条都绿后，再决定是否叠加关窗回传。若产品临时要求「预览也要水印」，只扩 Facade 的可选参数，不要新开平行 Helper。全仓检索 new OpenFileRequest 的命中数应保持为一；页面层只调用 openDoc。注释写清「本项目约定：水印与修订只走 Facade」，比口头说「参考 Demo」更耐看。周五用正式包包名再验注册，并对照日志里的 ready、沙箱、enableEdit、是否带水印、是否进修订，确认策略相关误报是否下降------这比写长周报更能反映对接质量。

从协作角度看，把水印文字与修订作者名做成可配置项（远程配置或本地常量均可），比写死在页面里更利于运营调整。颜色与角度属于视觉参数，联调阶段可先用对比明显的组合确认逻辑，再交给设计调淡。修订面板是否展示、是否静默进入，应在需求文档里写清默认值，避免不同页面各自猜。路径拷贝失败时要有明确错误提示，否则用户只会说「打不开」或「没有水印」，研发侧难以及时定位。把上述约定坚持几周，策略层相关的反复提问通常会明显减少，接入节奏也会更稳。

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。

官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT