HarmonyOS WPS Open SDK：关闭回传 URI-FD 与 ResultData 解析实现
在 HarmonyOS 应用中集成 WPS Open SDK 后OpenFileRequest负责把沙箱内的文档交给 WPS 进程编辑。编辑结束后最新文件内容往往落在 WPS 自身沙箱而非调用方传入的原始路径。若业务需要在关窗后继续上传或持久化必须在请求对象上启用关闭回传Transfer并在WPSApi.sendRequest的异步结果里解析Result/ResultData再把文件同步到本应用沙箱。本文按接口语义说明参数组合、URI 与 FD 两种回传路径的差异以及filePath落盘的参考实现。一、关闭回传在调用链中的位置典型时序如下应用构造OpenFileRequest并设置wpsTransferType→sendRequest拉起 WPS → 用户编辑并关闭文档 → Promise resolve此时result.data携带回传信息 → 应用侧拷贝或读 fd → 得到可用于上传的本地路径。若未配置enableTransferFile或wpsTransferTypesendRequest在 WPS 成功拉起后即可返回code ResultCode.OK但data为空。这与「回传成功」是两种语义UI 层应区分「已打开 WPS」与「已收到回传文件」避免在data为空时提示保存成功。二、ResultData 字段说明Result.data类型为ResultData与文件回传相关字段如下字段类型/含义fileUriURI 模式WPS 沙箱内临时文件路径transferFdFD 模式可读文件描述符transferFileNameFD 模式建议使用的文件名transferFileSizeFD 模式字节数用于校验读入是否完整parameters扩展字典部分版本 FD 信息嵌套在此sendRequest与回传相关的返回语义场景codedata未开回传拉起成功OK空开启回传用户关闭且成功OK含 fileUri 或 transferFd 等拉起失败或回传异常非 OK视版本可能为空或带错误信息三、开启回传的参数配置OpenFileRequest上两组相关属性参数说明enableTransferFile为true时按 URI 回传wpsTransferTypeTransferType.URI或TransferType.FD优先于enableTransferFile工程上建议只设置wpsTransferType避免两个开关语义重叠。enableEdit控制是否可编辑与回传独立可编辑场景通常同时开启。import{common}fromkit.AbilityKit;import{WPSApi,OpenFileRequest,TransferType,ResultCode,}fromwps/wps_sdk;asyncfunctionopenWithTransfer(ctx:common.UIAbilityContext,sandboxPath:string,mode:TransferTypeTransferType.URI){constrequestnewOpenFileRequest(ctx,sandboxPath);request.enableEdittrue;request.wpsTransferTypemode;constresultawaitWPSApi.sendRequest(request);if(result.code!ResultCode.OK){thrownewError(result.msg??WPS error${result.code});}returnresult;}四、URI 回传拷贝到本应用沙箱URI 模式下result.data.fileUri指向 WPS 维护的临时文件。三方应用应使用ohos.file.fs以只读方式打开再copyFileSync到例如context.filesDir/wps_callback/目录最后用fileuri.getUriFromPath转为业务使用的 URI。注意fileUri不能写入业务数据库作为长期路径拷贝前需mkdirSync专业版启用不落地时拷贝完成后可对 WPS 临时文件执行unlink。importfsfromohos.file.fs;importfileurifromohos.file.fileuri;functioncopyWpsUriToSandbox(ctx:common.UIAbilityContext,wpsFileUri:string):string{constfilefs.openSync(wpsFileUri,fs.OpenMode.READ_ONLY);constbaseNamewpsFileUri.split(/).pop()??edited.docx;constdestDir${ctx.filesDir}/wps_callback;fs.mkdirSync(destDir,true);constbackupPath${destDir}/${Date.now()}_${baseName};fs.copyFileSync(file.fd,backupPath);fs.closeSync(file);returnfileuri.getUriFromPath(backupPath);}五、FD 回传分块读取与关闭描述符FD 模式从transferFd分块readSync写入本应用沙箱新文件写完后必须closefd。实现时建议校验累计读取字节数与transferFileSize一致否则按失败处理避免上传残缺文件。大文件可将读写在TaskPool中执行避免阻塞 UI 线程。统一入口可先判断 FD再回退 URI与官方 Demo 中handleCallbackData/handleCallbackDataByFd的分支顺序一致functionresolveCallbackFilePath(ctx:common.UIAbilityContext,result:Result):string|undefined{constdataresult.data;if(!data)returnundefined;if(data.transferFd!undefineddata.transferFd0){returncopyFdToSandbox(ctx,data);// 按文档 Demo 实现}if(data.fileUri){returncopyWpsUriToSandbox(ctx,data.fileUri);}returnundefined;}六、联调与常见问题回调无 data未设置wpsTransferType或用户未关闭文档即切回应用。上传仍是旧文件业务仍使用打开前的sandboxPath未使用回传拷贝后的路径。拷贝失败目标目录未创建、沙箱权限不足、文件被占用。FD 泄漏读完后未closeSync(transferFd)。HAR 与凭据不匹配个人版测试包须使用申请时对应的 SDK 版本。建议测试矩阵小 docx / 大 xlsx 各测 URI 与 FD正常关窗、杀 WPS 进程两种路径拷贝后用本应用再次打开校验内容 hash。extraOptions、水印等参数与回传无冲突可配置在同一OpenFileRequest实例上。错误处理建议生产代码中应对sendRequest做完整分支code ! OK时向用户展示result.msg或映射后的错误文案code OK !result.data表示仅打开成功不应触发上传data非空但拷贝失败时与回传失败分开提示便于定位是 WPS 侧还是应用侧文件系统问题。单元测试可对resolveCallbackFilePath注入 MockResult覆盖空 data、仅 URI、仅 FD、size 不一致等分支。与不落地策略的配合专业版默认不落地时云文档数据流与本地回传无直接关系但 URI 模式下 WPS 仍可能产生临时文件。拷贝到本应用沙箱后若安全策略要求最小化残留应在确认上传成功后再删除 WPS 临时路径与本应用中间文件。个人版与个人版 HAR 的接口与专业版一致联调时注意包名、签名与申请凭据对应避免回调字段缺失被误判为未开回传。七、小结关闭回传把 WPS 编辑能力从「单向打开」扩展为「可回写」wpsTransferType声明传输层形态sendRequest的 Promise 承载关窗结果应用侧负责沙箱拷贝与后续业务消费。实现时固定「解析 Result → 拷贝/fd 读入 → 上传或落库」三层URI/FD 仅影响第二步的具体 API 调用。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT技术交流 QQ 群628436767
)
