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或wpsTransferType，sendRequest在 WPS 成功拉起后即可返回code === ResultCode.OK，但data为空。这与「回传成功」是两种语义，UI 层应区分「已打开 WPS」与「已收到回传文件」，避免在data为空时提示保存成功。

二、ResultData 字段说明

Result.data类型为ResultData，与文件回传相关字段如下：

字段	类型/含义
`fileUri`	URI 模式：WPS 沙箱内临时文件路径
`transferFd`	FD 模式：可读文件描述符
`transferFileName`	FD 模式：建议使用的文件名
`transferFileSize`	FD 模式：字节数，用于校验读入是否完整
`parameters`	扩展字典，部分版本 FD 信息嵌套在此

sendRequest与回传相关的返回语义：

场景	code	data
未开回传，拉起成功	OK	空
开启回传，用户关闭且成功	OK	含 fileUri 或 transferFd 等
拉起失败或回传异常	非 OK	视版本可能为空或带错误信息

三、开启回传的参数配置

OpenFileRequest上两组相关属性：

参数	说明
`enableTransferFile`	为`true`时按 URI 回传
`wpsTransferType`	`TransferType.URI`或`TransferType.FD`，优先于`enableTransferFile`

工程上建议只设置wpsTransferType，避免两个开关语义重叠。enableEdit控制是否可编辑，与回传独立，可编辑场景通常同时开启。

import{common}from'@kit.AbilityKit';import{WPSApi,OpenFileRequest,TransferType,ResultCode,}from'@wps/wps_sdk';asyncfunctionopenWithTransfer(ctx:common.UIAbilityContext,sandboxPath:string,mode:TransferType=TransferType.URI){constrequest=newOpenFileRequest(ctx,sandboxPath);request.enableEdit=true;request.wpsTransferType=mode;constresult=awaitWPSApi.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。

importfsfrom'@ohos.file.fs';importfileurifrom'@ohos.file.fileuri';functioncopyWpsUriToSandbox(ctx:common.UIAbilityContext,wpsFileUri:string):string{constfile=fs.openSync(wpsFileUri,fs.OpenMode.READ_ONLY);constbaseName=wpsFileUri.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{constdata=result.data;if(!data)returnundefined;if(data.transferFd!==undefined&&data.transferFd>=0){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 调用。