在 HarmonyOS 应用中集成wps/wps_sdk时业务侧常把「能否打开 Word」当成单一验收点。工程落地后会发现只读/可编辑、水印、菜单开关、关窗回传、是否允许落地分别落在不同字段上。本文按registerApp→OpenFileRequest→Result的调用链把能力对齐到具体参数便于代码评审与联调归因字段语义以官方对接文档为准。一、能力在调用链中的位置典型时序如下RegisterAppRequest成功 → 构造OpenFileRequest并写入能力字段 →WPSApi.sendRequest拉起 WPS → 用户编辑或预览 →若开启回传关窗后 Promise resolveresult.data携带文件信息。建议按层叠加而不是一次写满所有开关层级能力主要入口接入层应用注册、可选激活序列号RegisterAppRequest/setWpsFileToken打开层拉起 WPS、只读/可编辑OpenFileRequest.enableEdit策略层水印、修订、菜单、不落地wpsWaterMarkParams/extraOptions/enableLocalization结果层关窗后拿回文件wpsTransferType/Result.data一次堆满参数时ResultCode.ERROR很难归因。联调应先跑通「注册 → 沙箱路径 → 只读打开」再开可编辑最后叠水印、extraOptions与回传。二、接入层registerApp 与激活对接文档要求registerApp成功之前调用其它sendRequest会 reject。这不是「打开失败」而是请求链尚未就绪。注册成功后若凭据形态需要序列号再调用setWpsFileToken是否注入序列号应依据当前 HAR / 凭据约定不要用包名猜测。import{common}fromkit.AbilityKit;import{WPSApi,RegisterAppRequest,OpenFileRequest,OpenFileExtraOptions,WaterMark,TransferType,ResultCode,}fromwps/wps_sdk;letwpsReadyfalse;asyncfunctionensureRegistered(ctx:common.UIAbilityContext,activationSn?:string):Promisevoid{if(wpsReady)return;constrawaitWPSApi.sendRequest(newRegisterAppRequest(ctx,APP_KEY,APP_SECRET));if(r.codeResultCode.ERROR_CODE_AUTH_FAILURE){thrownewError(1013:${r.msg??});}if(r.code!ResultCode.OK){thrownewError(register${r.code});}if(activationSn){WPSApi.setWpsFileToken(activationSn);}wpsReadytrue;}冷启动可在Application.onCreate中await ensureRegistered首页打开按钮在wpsReady前禁用。Release 不要打印完整 secret。换 HAR 或换 flavor 后务必 clean核对bundleName与申请凭据一致否则会出现调试包正常、正式包 1013。三、打开层enableEdit 与沙箱路径默认只读是能力语义不是缺陷enableEdit未设或为false时以只读打开只有显式true才是可编辑。预览入口与编辑入口应共用同一打开函数只差布尔参数避免两套new OpenFileRequest漂移。路径侧建议先把选择器文件copyFileSync到filesDir再传沙箱路径。直接传外部 URI 时权限不足常直接落到ResultCode.ERROR日志里又看不到明确「权限」文案。参数说明构造参数filePath建议为本应用沙箱内可读路径enableEdittrue可编辑默认/false只读与回传关系独立可编辑场景通常同时开wpsTransferType四、策略层水印、extraOptions 与不落地水印通过wpsWaterMarkParamsWaterMark注入文字、角度、颜色与字号。修订通过wpsRevisionParams控制作者名与是否进入修订模式。菜单级能力走extraOptionsOpenFileExtraOptions分享、云文档、打印、导出、截图、复制粘贴等仅显式赋值的字段生效。不落地由enableLocalization控制且与当前 HAR / 凭据形态相关未允许落地时云文档、分享、打印等可能被 SDK 强制关闭即便extraOptions写成true也无效。方案评审时应先确认是否允许落地再讨论菜单矩阵否则真机上会出现「改了开关却没变化」。importfsfromohos.file.fs;functiontoSandbox(ctx:common.UIAbilityContext,src:string):string{constdir${ctx.filesDir}/wps_cap;fs.mkdirSync(dir,true);constdest${dir}/${Date.now()}.docx;fs.copyFileSync(src,dest);returndest;}asyncfunctionopenWithCapability(ctx:common.UIAbilityContext,src:string,opts:{editable:boolean;watermark?:string;transfer?:boolean;lockShare?:boolean;}){awaitensureRegistered(ctx);constpathtoSandbox(ctx,src);constreqnewOpenFileRequest(ctx,path);req.enableEditopts.editable;if(opts.watermark){constwmnewWaterMark();wm.Enabletrue;wm.WaterMaskTextopts.watermark;wm.Angle-30;wm.FontColor#19000000;wm.FontSize16;req.wpsWaterMarkParamswm;}if(opts.transfer){req.wpsTransferTypeTransferType.URI;}if(opts.lockShare){constextranewOpenFileExtraOptions();extra.enableSharefalse;extra.enableCloudfalse;extra.enablePrintfalse;extra.enableExportfalse;req.extraOptionsextra;}constresawaitWPSApi.sendRequest(req);if(res.code!ResultCode.OK){thrownewError(res.msg??String(res.code));}returnres;}工程上建议把场景 → 字段收成配置表页面只调openWithCapability。Code review 盯时序与路径而不是每个页面复制一份extraOptions。五、结果层关闭回传与 ResultData关窗回传不是「切回应用」。未设置enableTransferFile/wpsTransferType时SDK 只负责拉起 WPS关闭后不一定回传文件。需要编辑结果时再设TransferType.URI或FD。场景codedata未开回传拉起成功OK空开启回传用户关闭且成功OK含fileUri或transferFd等拉起失败或回传异常非 OK视版本可能为空OK !data常见于用户尚未关窗不要当成失败 toast。拿到fileUri后用只读打开 copyFileSync落到本应用目录再上传不要把 WPS 临时路径写入业务库当作长期路径。asyncfunctionopenAndCollect(ctx:common.UIAbilityContext,src:string){constresawaitopenWithCapability(ctx,src,{editable:true,transfer:true,watermark:${uid}|内部,lockShare:true,});if(!res.data?.fileUri){returnnull;}constffs.openSync(res.data.fileUri,fs.OpenMode.READ_ONLY);constdest${ctx.filesDir}/wps_out/${Date.now()}.docx;fs.mkdirSync(${ctx.filesDir}/wps_out,true);fs.copyFileSync(f.fd,dest);fs.closeSync(f);returndest;}六、联调与常见问题其它请求直接 reject未先registerApp或注册失败仍继续打开。始终只读未设enableEdit true或两套打开入口字段不一致。菜单改了无效处于不落地约束或extraOptions未显式赋值。回调无 data未设wpsTransferType或用户未关闭文档即切回应用。上传仍是旧文件业务仍使用打开前的sandboxPath未使用回传拷贝后的路径。1013 / 鉴权失败bundleName、签名与申请凭据不匹配或 HAR 未 clean。建议测试矩阵小 docx / 大 xlsx只读与可编辑有无水印有无lockShareURI 回传正常关窗与杀进程。日志按层拆开注册层只关心1013与OK打开层关心ERROR与路径策略层用真机菜单验证回传层单独断言data。单测至少覆盖ensureRegistered短路、openWithCapability在editablefalse/true下的字段差异以及回传缺失时的空data分支。多人协作时禁止页面直接new OpenFileRequest新增能力只扩展选项对象由统一buildRequest写入字段。机型与客户端差异会放大策略层不确定性。菜单与预期不符时先对照文档中不落地强制关闭列表再核对extraOptions是否显式赋值。HAR 升级后把OpenFileRequest、WaterMark、OpenFileExtraOptions、TransferType相关字段扫一遍即可。生产代码应对sendRequest做完整分支code ! OK时展示result.msg或映射后的错误文案code OK !result.data表示仅打开成功不应触发上传data非空但拷贝失败时与回传失败分开提示便于定位是 WPS 侧还是应用侧文件系统问题。水印、extraOptions与回传可配置在同一OpenFileRequest实例上彼此无互斥但联调仍建议按层打开避免一次变更过多字段。七、小结鸿蒙侧 WPS Open SDK 的能力面本质是一组可组合的请求参数与回调语义接入层保证请求链可用打开层决定读写模式策略层约束菜单与水印结果层决定关窗后能否回写业务。实现时固定「注册 → 沙箱路径 → 按场景写字段 → 按层断言 Result」四步联调成本会明显下降。字段表与枚举以官方对接文档为准把能力封装进统一模块后日常需求通常只改水印文案或上传层不必再打穿整条链路。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT
HarmonyOS WPS Open SDK：OpenFileRequest 能力分层与参数映射实现
在 HarmonyOS 应用中集成wps/wps_sdk时业务侧常把「能否打开 Word」当成单一验收点。工程落地后会发现只读/可编辑、水印、菜单开关、关窗回传、是否允许落地分别落在不同字段上。本文按registerApp→OpenFileRequest→Result的调用链把能力对齐到具体参数便于代码评审与联调归因字段语义以官方对接文档为准。一、能力在调用链中的位置典型时序如下RegisterAppRequest成功 → 构造OpenFileRequest并写入能力字段 →WPSApi.sendRequest拉起 WPS → 用户编辑或预览 →若开启回传关窗后 Promise resolveresult.data携带文件信息。建议按层叠加而不是一次写满所有开关层级能力主要入口接入层应用注册、可选激活序列号RegisterAppRequest/setWpsFileToken打开层拉起 WPS、只读/可编辑OpenFileRequest.enableEdit策略层水印、修订、菜单、不落地wpsWaterMarkParams/extraOptions/enableLocalization结果层关窗后拿回文件wpsTransferType/Result.data一次堆满参数时ResultCode.ERROR很难归因。联调应先跑通「注册 → 沙箱路径 → 只读打开」再开可编辑最后叠水印、extraOptions与回传。二、接入层registerApp 与激活对接文档要求registerApp成功之前调用其它sendRequest会 reject。这不是「打开失败」而是请求链尚未就绪。注册成功后若凭据形态需要序列号再调用setWpsFileToken是否注入序列号应依据当前 HAR / 凭据约定不要用包名猜测。import{common}fromkit.AbilityKit;import{WPSApi,RegisterAppRequest,OpenFileRequest,OpenFileExtraOptions,WaterMark,TransferType,ResultCode,}fromwps/wps_sdk;letwpsReadyfalse;asyncfunctionensureRegistered(ctx:common.UIAbilityContext,activationSn?:string):Promisevoid{if(wpsReady)return;constrawaitWPSApi.sendRequest(newRegisterAppRequest(ctx,APP_KEY,APP_SECRET));if(r.codeResultCode.ERROR_CODE_AUTH_FAILURE){thrownewError(1013:${r.msg??});}if(r.code!ResultCode.OK){thrownewError(register${r.code});}if(activationSn){WPSApi.setWpsFileToken(activationSn);}wpsReadytrue;}冷启动可在Application.onCreate中await ensureRegistered首页打开按钮在wpsReady前禁用。Release 不要打印完整 secret。换 HAR 或换 flavor 后务必 clean核对bundleName与申请凭据一致否则会出现调试包正常、正式包 1013。三、打开层enableEdit 与沙箱路径默认只读是能力语义不是缺陷enableEdit未设或为false时以只读打开只有显式true才是可编辑。预览入口与编辑入口应共用同一打开函数只差布尔参数避免两套new OpenFileRequest漂移。路径侧建议先把选择器文件copyFileSync到filesDir再传沙箱路径。直接传外部 URI 时权限不足常直接落到ResultCode.ERROR日志里又看不到明确「权限」文案。参数说明构造参数filePath建议为本应用沙箱内可读路径enableEdittrue可编辑默认/false只读与回传关系独立可编辑场景通常同时开wpsTransferType四、策略层水印、extraOptions 与不落地水印通过wpsWaterMarkParamsWaterMark注入文字、角度、颜色与字号。修订通过wpsRevisionParams控制作者名与是否进入修订模式。菜单级能力走extraOptionsOpenFileExtraOptions分享、云文档、打印、导出、截图、复制粘贴等仅显式赋值的字段生效。不落地由enableLocalization控制且与当前 HAR / 凭据形态相关未允许落地时云文档、分享、打印等可能被 SDK 强制关闭即便extraOptions写成true也无效。方案评审时应先确认是否允许落地再讨论菜单矩阵否则真机上会出现「改了开关却没变化」。importfsfromohos.file.fs;functiontoSandbox(ctx:common.UIAbilityContext,src:string):string{constdir${ctx.filesDir}/wps_cap;fs.mkdirSync(dir,true);constdest${dir}/${Date.now()}.docx;fs.copyFileSync(src,dest);returndest;}asyncfunctionopenWithCapability(ctx:common.UIAbilityContext,src:string,opts:{editable:boolean;watermark?:string;transfer?:boolean;lockShare?:boolean;}){awaitensureRegistered(ctx);constpathtoSandbox(ctx,src);constreqnewOpenFileRequest(ctx,path);req.enableEditopts.editable;if(opts.watermark){constwmnewWaterMark();wm.Enabletrue;wm.WaterMaskTextopts.watermark;wm.Angle-30;wm.FontColor#19000000;wm.FontSize16;req.wpsWaterMarkParamswm;}if(opts.transfer){req.wpsTransferTypeTransferType.URI;}if(opts.lockShare){constextranewOpenFileExtraOptions();extra.enableSharefalse;extra.enableCloudfalse;extra.enablePrintfalse;extra.enableExportfalse;req.extraOptionsextra;}constresawaitWPSApi.sendRequest(req);if(res.code!ResultCode.OK){thrownewError(res.msg??String(res.code));}returnres;}工程上建议把场景 → 字段收成配置表页面只调openWithCapability。Code review 盯时序与路径而不是每个页面复制一份extraOptions。五、结果层关闭回传与 ResultData关窗回传不是「切回应用」。未设置enableTransferFile/wpsTransferType时SDK 只负责拉起 WPS关闭后不一定回传文件。需要编辑结果时再设TransferType.URI或FD。场景codedata未开回传拉起成功OK空开启回传用户关闭且成功OK含fileUri或transferFd等拉起失败或回传异常非 OK视版本可能为空OK !data常见于用户尚未关窗不要当成失败 toast。拿到fileUri后用只读打开 copyFileSync落到本应用目录再上传不要把 WPS 临时路径写入业务库当作长期路径。asyncfunctionopenAndCollect(ctx:common.UIAbilityContext,src:string){constresawaitopenWithCapability(ctx,src,{editable:true,transfer:true,watermark:${uid}|内部,lockShare:true,});if(!res.data?.fileUri){returnnull;}constffs.openSync(res.data.fileUri,fs.OpenMode.READ_ONLY);constdest${ctx.filesDir}/wps_out/${Date.now()}.docx;fs.mkdirSync(${ctx.filesDir}/wps_out,true);fs.copyFileSync(f.fd,dest);fs.closeSync(f);returndest;}六、联调与常见问题其它请求直接 reject未先registerApp或注册失败仍继续打开。始终只读未设enableEdit true或两套打开入口字段不一致。菜单改了无效处于不落地约束或extraOptions未显式赋值。回调无 data未设wpsTransferType或用户未关闭文档即切回应用。上传仍是旧文件业务仍使用打开前的sandboxPath未使用回传拷贝后的路径。1013 / 鉴权失败bundleName、签名与申请凭据不匹配或 HAR 未 clean。建议测试矩阵小 docx / 大 xlsx只读与可编辑有无水印有无lockShareURI 回传正常关窗与杀进程。日志按层拆开注册层只关心1013与OK打开层关心ERROR与路径策略层用真机菜单验证回传层单独断言data。单测至少覆盖ensureRegistered短路、openWithCapability在editablefalse/true下的字段差异以及回传缺失时的空data分支。多人协作时禁止页面直接new OpenFileRequest新增能力只扩展选项对象由统一buildRequest写入字段。机型与客户端差异会放大策略层不确定性。菜单与预期不符时先对照文档中不落地强制关闭列表再核对extraOptions是否显式赋值。HAR 升级后把OpenFileRequest、WaterMark、OpenFileExtraOptions、TransferType相关字段扫一遍即可。生产代码应对sendRequest做完整分支code ! OK时展示result.msg或映射后的错误文案code OK !result.data表示仅打开成功不应触发上传data非空但拷贝失败时与回传失败分开提示便于定位是 WPS 侧还是应用侧文件系统问题。水印、extraOptions与回传可配置在同一OpenFileRequest实例上彼此无互斥但联调仍建议按层打开避免一次变更过多字段。七、小结鸿蒙侧 WPS Open SDK 的能力面本质是一组可组合的请求参数与回调语义接入层保证请求链可用打开层决定读写模式策略层约束菜单与水印结果层决定关窗后能否回写业务。实现时固定「注册 → 沙箱路径 → 按场景写字段 → 按层断言 Result」四步联调成本会明显下降。字段表与枚举以官方对接文档为准把能力封装进统一模块后日常需求通常只改水印文案或上传层不必再打穿整条链路。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT
