HarmonyOS 工程接入wps/wps_sdk后本地文档打开通常先跑通registerApp、沙箱路径与enableEdit。产品下一步常会要求「预览页打水印」或「以修订模式进入文档」。对接文档把这两类能力挂在同一次OpenFileRequest上水印走wpsWaterMarkParams类型WaterMark修订走wpsRevisionParams类型Revision。它们不是第二条打开 API而是打开策略层字段。本文按调用链写清字段语义、与只读/可编辑的叠加顺序、可复用封装与联调清单。字段以官方对接文档为准。一、策略层在打开链路中的位置固定顺序HAR 集成 →registerApp回调到ResultCode.OK→ 按凭据约定可选注入激活序列号 → 文件进入本应用沙箱 →new OpenFileRequest(context, path)→ 设置enableEdit→可选写入水印 / 修订 →WPSApi.sendRequest。层级职责入口门禁注册成功才允许打开registerApp/ResultCode.OK路径选择器 URI 拷进沙箱filesDir拷贝模式只读或可编辑enableEdit策略水印、修订wpsWaterMarkParams/wpsRevisionParams结果关窗回传可选wpsTransferType水印与修订属于策略层不要和「能否打开」绑在同一个匿名点击回调里同时改。联调建议注册 → 沙箱只读 → 可编辑 → 再叠水印或修订 → 最后回传。一次写满全部开关时ResultCode.ERROR很难归因。二、WaterMark 字段语义类型WaterMark赋给request.wpsWaterMarkParams。属性说明Enable是否启用水印WaterMaskText水印文字Angle旋转角度FontColor颜色可含透明度如#19000000FontSize字号常见漏项只new WaterMark()却未设Enable true文字为空却期望看见水印对象建了却未赋给 Request。封装时应写完字段再赋值。水印可与只读同时存在预览场景不必强行enableEdit true。颜色过淡时联调可先用对比更明显的组合确认逻辑再交给设计调淡。import{WaterMark,OpenFileRequest}fromwps/wps_sdk;functionapplyWatermark(req:OpenFileRequest,text:string):void{constwmnewWaterMark();wm.Enabletrue;wm.WaterMaskTexttext;wm.Angle-30;wm.FontColor#19000000;wm.FontSize24;req.wpsWaterMarkParamswm;}三、Revision 字段语义类型Revision赋给request.wpsRevisionParams。属性说明UserName修订作者名称EnterReviseMode是否以修订模式打开ShowRevisionPanel是否显示修订面板EnterRevisionSilent是否静默进入不弹提示修订痕迹依赖可编辑。若enableEdit仍为只读用户侧常感觉「修订没生效」。EnterRevisionSilent适合减少打扰联调日志仍要打出是否进入修订。UserName建议与业务登录名或工号对齐便于事后追溯。import{Revision}fromwps/wps_sdk;functionapplyRevision(req:OpenFileRequest,user:string,silent:boolean):void{constrevnewRevision();rev.UserNameuser;rev.EnterReviseModetrue;rev.ShowRevisionPaneltrue;rev.EnterRevisionSilentsilent;req.wpsRevisionParamsrev;}四、注册就绪与路径前提未注册成功就sendRequest会抛异常此时讨论水印无效。把注册收成可await的准备换 HAR 或换正式包包名后 clean再验注册。1013ERROR_CODE_AUTH_FAILURE出现在注册阶段时停止改策略字段先对齐bundleName、appKey/appSecret与 HAR。import{WPSApi,Result,ResultCode}fromwps/wps_sdk;letreadyfalse;exportfunctionprepareWps(key:string,secret:string,sn?:string):Promisevoid{returnnewPromise((resolve,reject){if(ready){resolve();return;}WPSApi.registerApp(key,secret,{onCallback:(result:Result):void{if(result.codeResultCode.ERROR_CODE_AUTH_FAILURE){reject(newError(1013:${result.msg??}));return;}if(result.code!ResultCode.OK){reject(newError(register${result.code}));return;}if(sn){WPSApi.setWpsFileToken(sn);}readytrue;resolve();},});});}路径建议先拷到沙箱外部 URI 权限不足时常见泛化ERROR容易被误判成「水印没生效」。需要序列号时在注册成功回调里全局注入不要写OpenFileRequest.wpsToken。Release 禁止打印完整appSecret。五、可复用打开封装把模式、水印、修订做成可选参数页面不直接new OpenFileRequest。import{common}fromkit.AbilityKit;import{OpenFileRequest,Result,WPSApi}fromwps/wps_sdk;exporttypeOpenModepreview|edit;exportinterfaceOpenPolicy{watermarkText?:string;revisionUser?:string;revisionSilent?:boolean;}exportasyncfunctionopenDoc(ctx:common.UIAbilityContext,src:string,mode:OpenMode,policy:OpenPolicy{}):PromiseResult{awaitprepareWps(APP_KEY,APP_SECRET);constpathcopyToSandbox(ctx,src);constreqnewOpenFileRequest(ctx,path);req.enableEditmodeedit;if(policy.watermarkText){applyWatermark(req,policy.watermarkText);}if(policy.revisionUser){applyRevision(req,policy.revisionUser,!!policy.revisionSilent);}returnWPSApi.sendRequest(req);}产品临时加「预览也要水印」只扩policy不新开平行 Helper。关窗回传仍用独立字段与水印/修订解耦未开回传时ResultCode.OK且data null表示拉起成功不代表「已同步」。六、联调表与日志现象优先查抛异常是否等注册完成1013凭据 / 正式包包名 / clean无水印Enable、文字、是否赋给 Request无修订EnterReviseMode、是否可编辑泛化 ERROR路径是否沙箱日志固定code/msg/ ready / 沙箱 /enableEdit/ 是否带水印 / 是否进修订。全仓new OpenFileRequest命中保持一处。推荐验收两条用例只读预览 水印可编辑 修订静默开/关各测一次。两条都绿后再决定是否叠加关窗回传。七、小结与工程落地建议鸿蒙侧 WPS Open SDK 的水印与修订是打开策略层能力在enableEdit跑绿后再叠WaterMark/Revision。字段必须显式赋值封装用可选策略对象收口。路径进沙箱、注册先就绪、回传另算一层。字段语义以官方对接文档为准。接入评审可逐项确认当前 HAR 批次与包名是否匹配、沙箱目录约定是否统一、策略是否全部走 Facade、正式包与调试包的凭据是否分开归档。把「先模式后策略」写进联调清单后排查会从猜原因变成对表。换 HAR 后务必 clean 再装水印文字与修订作者名做成可配置项比写死在页面里更利于运营调整。注释写清「本项目约定水印与修订只走 Facade」比口头说「参考 Demo」更耐看。真机验收可拆成两条固定用例其一「只读预览 水印」其二「可编辑 修订含静默开关各测一次」。两条都绿后再决定是否叠加关窗回传。若产品临时要求「预览也要水印」只扩 Facade 的可选参数不要新开平行 Helper。全仓检索new OpenFileRequest的命中数应保持为一页面层只调用openDoc。周五用正式包包名再验注册并对照日志里的 ready、沙箱、enableEdit、是否带水印、是否进修订确认策略相关误报是否下降。从协作角度看颜色与角度属于视觉参数联调阶段可先用对比明显的组合确认逻辑再交给设计调淡。修订面板是否展示、是否静默进入应在需求文档里写清默认值避免不同页面各自猜。路径拷贝失败时要有明确错误提示否则用户只会说「打不开」或「没有水印」研发侧难以及时定位。Ability 启动阶段完成注册进入文档页前ready已同步到 UI点开时再构造 Request不要在aboutToAppear里预建一堆策略对象。Release 包禁止打印完整appSecret水印全文若含敏感信息日志侧只打文字长度更稳妥。把上述约定坚持几周策略层相关的反复提问通常会明显减少接入节奏也会更稳。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT