uni-app 鸿蒙与 Web 跨线程高效数据传输uts-worker-sendable-transfer UTS 插件原理与实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读本篇文章围绕 uni-app 仓库中 uts-worker-sendable-transfer 这一 UTS 插件模块展开讲解如何在 uni-appuni-app-x中通过 UTS 插件封装 Worker 的创建、消息收发与销毁并在鸿蒙HarmonyOS平台使用 ArkTS Sendable 对象、在 Web 平台使用 Transferable 对象实现跨线程大数据的高效传输。读完本文你将掌握该插件的 API 设计、底层调用关系、完整接入流程以及自动化测试验证方法可直接在自有项目中复用它完成 Worker 多线程通信。模块定位与适用场景uts-worker-sendable-transfer是一个以uts插件形式发布在uni_modules目录下的 UTS 插件模块其目录结构如下src/uni_modules/uts-worker-sendable-transfer/ ├── utssdk/ │ ├── index.uts # 插件主实现UTSSendableWorkerImpl 类 │ ├── interface.uts # 对外暴露的类型定义 │ └── sendable.ets # HarmonyOS Sendable 标记的可共享对象 ├── changelog.md # 更新日志当前为空 ├── package.json # 插件元信息与平台支持声明 └── readme.md # 开发文档入口从 package.json 可以看到该插件的工程约束类型为utsdcloudext.type要求 HBuilderX^3.6.8、uni-app / uni-app-x^3.1.0且为免费插件price: 0.00。该模块解决的核心问题是当主线程与 Worker 线程之间需要传递较大数据如 ArrayBuffer 二进制或共享对象时默认的结构化克隆/序列化拷贝开销大、耗时长。为此插件对外提供两种平台级的高效通道HarmonyOSSendable 对象通过postMessageWithSharedSendable实现共享引用传输避免拷贝WebTransferable 对象通过所有权转移传输 ArrayBuffer 等转移后原缓冲区长度变为 0。从源码结构看index.uts插件对外只暴露一个核心类UTSSendableWorkerImpl内部持有Worker实例与消息监听回调封装了创建—发送—监听—销毁的完整生命周期。核心类型定义与 API 说明插件通过 interface.uts 对外暴露全部类型并在 index.uts 中通过export *一并转发类型说明关键字段UTSWorkerAddListenerOptions添加消息监听的入参success?: UTSWorkerReceiveEventCallbackUTSWorkerAddListenerOptionsSuccess消息回调的结果对象result: UTSJSONObjectUTSWorkerSendWorkerMessageOptions发送消息的入参message: Object、harmonySendable?: boolean、transfer?: ArrayBuffer[]UTSWorkerReceiveEventCallback接收回调函数类型(callback: UTSWorkerAddListenerOptionsSuccess) voidUTSSendableWorkerImpl插件主类create()/sendMessage()/onMessage()/destroy()其中发送参数的三个字段含义如下message要发送给 Worker 的数据任意ObjectharmonySendable是否将消息包装为符合 Sendable 协议的对象发送仅鸿蒙生效默认不开启即走普通序列化拷贝transfer可转移的ArrayBuffer[]数组转移后主线程侧原缓冲区被掏空Web 平台表现明显byteLength变为 0。UTSSendableWorkerImpl 生命周期方法create()负责创建 Worker。源码index.uts中先检查是否已有实例若已存在会打印告警并先销毁旧实例随后调用uni.createWorker(workers/sendableTransferWorker.uts)创建指向src/workers/下 Worker 脚本的实例。这保证了单例语义避免重复创建造成资源泄漏。sendMessage()的发送逻辑index.uts值得展开当harmonySendable为真且处于APP-HARMONY条件编译分支时消息会被替换为 sendable.ets 中定义的SendableObject实例——这是一个用Sendable注解标记的 ArkTS 类字段a: number 45会被作为共享数据传给 Worker随后调用worker.postMessage(message, { harmonySendable, transfer })完成真正发送。onMessage()注册监听index.uts内部调用底层worker.onMessage收到消息后把原始结果包装为UTSWorkerAddListenerOptionsSuccessresult为UTSJSONObject再回调给用户。destroy()负责清理index.uts调用worker.terminate()结束 Worker 线程并置空内部引用与回调避免悬挂引用。与底层 uni.createWorker API 的对应关系该插件是底层uni.createWorker能力uni-createWorker 模块的上层封装。在 uni-createWorker 的类型定义 中Worker.postMessage的WorkerPostMessageOptions与插件参数一一对应harmonySendable?: boolean——注释明确说明是否支持符合 Sendable 协议的对象作为共享变量发送使用 postMessageWithSharedSendable 实现默认值为 false仅鸿蒙平台支持unixVer 4.81、unixVaporVer 5.0 起transfer?: any[]——可转移对象数组默认值为空数组仅鸿蒙、web 平台支持web 端 unixVer 4.81 起。也就是说插件在鸿蒙端通过postMessageWithSharedSendable走共享引用通道在 Web 端通过 Transferable objects 走所有权转移通道而在 Android、iOS 等平台这些参数被忽略退化为常规序列化传输。此外底层 Worker 接口 还提供了envWorker 内环境变量如USER_DATA_PATH、onError错误监听与terminate()。与 Worker 相关的错误码也定义在同文件中interface.uts5000501Worker 运行错误、5000502序列化失败、5000503实例未运行、5000504Worker 线程中不支持调用的 API、5000505初始化失败、5000506文件路径无效、5000510非主线程调用、5000511Worker 线程无效便于开发者在onError中做精细化排障。完整实战在页面中接入该插件仓库在 worker-sendable-transfer.uvue 提供了完整可运行的演示页面接入步骤清晰1. 引入插件并实例化import { UTSWorkerAddListenerOptions, UTSWorkerReceiveEventCallback, UTSWorkerSendWorkerMessageOptions, UTSSendableWorkerImpl } from /uni_modules/uts-worker-sendable-transfer; const sendableWorker new UTSSendableWorkerImpl()页面同时准备了一个 8 字节的ArrayBuffer作为二进制传输样本const myBuf ref(new ArrayBuffer(8)) const data reactive({ myBufLength: -1, sendableNumber: 0, } as DataType)2. 创建 Worker 并注册消息监听function create() { sendableWorker.create() workerStatus.value created; // 添加消息监听 sendableWorker.onMessage({ success: (res) { const result res.result; // #ifdef APP-HARMONY // 这里经过 worker 修改后result.a 应该是 666 data.sendableNumber result.a // #endif addLog(收到WorkerTask返回: ${JSON.stringify(result)}, receive); } }); }3. 发送消息Sendable Transferable 双通道function sendMessage() { data.myBufLength myBuf.value.byteLength sendableWorker.sendMessage({ message: 这里是主线程发送的 message, harmonySendable: true, transfer: [myBuf.value] }) // NOTE: HarmonyOS 长度不变web 长度变为 0 data.myBufLength myBuf.value.byteLength }发送后再次读取myBuf.byteLength在HarmonyOS 上长度保持不变Sendable 共享引用不搬移缓冲区而在Web 上长度变为 0Transferable 把ArrayBuffer所有权转移给了 Worker。4. 页面卸载时销毁onUnload(() { destory(); }) function destory() { sendableWorker.destroy() workerStatus.value destroyed; }Worker 端脚本实现Worker 线程脚本位于 sendableTransferWorker.uts继承WorkerTaskImpl并实现两个钩子entry()Worker 启动入口打印初始化日志onMessage(message)接收主线程消息。在APP-HARMONY分支下若检测到消息是带数字字段a的对象就把它改写为666然后postMessage原样回发从而验证 Sendable 对象是共享引用——Worker 的修改主线程直接可见。export class SendableTransferWorker extends WorkerTaskImpl { override entry() { console.log([WorkerTask] HelloWorkerTask 启动完成等待主线程消息); } override onMessage(message : any) { // #ifdef APP-HARMONY if (typeof message object typeof (message as ESObject).a number) { (message as ESObject).a 666 } // #endif this.sendReply(message); } }自动化测试验证跨平台行为差异仓库在 worker-sendable-transfer.test.js 中对该能力做了端到端自动化测试测试只对harmony与web两个平台生效其余平台直接跳过流程为program.reLaunch打开演示页并等待 500ms调用页面暴露的create方法创建 Worker调用sendMessage发送消息断言两个关键数据data.myBufLengthHarmonyOS 上期望为 8缓冲区未被转移Web 上期望为 0缓冲区所有权已转移data.sendableNumberHarmonyOS 上期望为 666Sendable 对象被 Worker 修改后共享可见。这两个断言恰好从测试层面印证了上文所述的平台差异可作为回归用例持续守护该能力。使用注意事项与平台差异小结综合源码与测试使用该插件时需注意以下几点平台适用性harmonySendable仅鸿蒙uni-app-x 4.81 / Vapor 5.0 起支持transfer仅鸿蒙与 Web 支持Android、iOS 及小程序端不受影响参数被忽略。transfer的副作用在 Web 端ArrayBuffer被转移后主线程原引用byteLength变为 0若仍需在主线程使用该缓冲请先拷贝或提前读取鸿蒙端因 Sendable 是共享引用长度不变。生命周期管理create()具备先销毁旧实例再创建的幂等保护务必在页面onUnload中调用destroy()释放 Worker 线程避免后台常驻线程导致内存问题。条件编译SendableObject仅存在于APP-HARMONY分支index.uts其他平台编译时会自动剔除相关代码演示页面中result.a的读取同样放在#ifdef APP-HARMONY内。Worker 脚本路径uni.createWorker(workers/sendableTransferWorker.uts)指向src/workers/目录若在自有项目中使用请按实际目录放置脚本。相关学习资源该插件 readme 中指向的 UTS 开发资料在仓库docs目录下均有对应文档可供查阅UTS 语法总览docs/uts/README.mdUTS 插件开发含插件结构、manifest 配置docs/plugin/uts-plugin.mduni-app 兼容模式下使用 UTS 组件docs/plugin/uts-component.md标准模式uni-app-xUTS 组件docs/plugin/uts-component-vue.md各平台原生能力接入docs/plugin/uts-for-android.md、docs/plugin/uts-for-ios.md、docs/plugin/uts-for-harmony.md官方示例工程 Hello UTS 的仓库内镜像examples/hello-uts以及对应的 uni-app-x 版示例 examples/hello-uvue总结uts-worker-sendable-transfer是 uni-app 仓库中一个结构精简但功能定位明确的 UTS 插件它以UTSSendableWorkerImpl类封装 Worker 全生命周期把 HarmonyOS 的 Sendable 共享引用传输与 Web 的 Transferable 所有权转移统一到sendMessage的两个参数之下配合条件编译实现对多端的一致 API 与差异化的底层传输策略。开发者可直接将src/uni_modules/uts-worker-sendable-transfer目录复制进自己的uni_modules参考src/pages/API/create-worker/worker-sendable-transfer.uvue的接入方式快速落地并使用仓库中已有的自动化测试用例保障跨平台行为正确性。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app 鸿蒙与 Web 跨线程高效数据传输：uts-worker-sendable-transfer UTS 插件原理与实战
uni-app 鸿蒙与 Web 跨线程高效数据传输uts-worker-sendable-transfer UTS 插件原理与实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读本篇文章围绕 uni-app 仓库中 uts-worker-sendable-transfer 这一 UTS 插件模块展开讲解如何在 uni-appuni-app-x中通过 UTS 插件封装 Worker 的创建、消息收发与销毁并在鸿蒙HarmonyOS平台使用 ArkTS Sendable 对象、在 Web 平台使用 Transferable 对象实现跨线程大数据的高效传输。读完本文你将掌握该插件的 API 设计、底层调用关系、完整接入流程以及自动化测试验证方法可直接在自有项目中复用它完成 Worker 多线程通信。模块定位与适用场景uts-worker-sendable-transfer是一个以uts插件形式发布在uni_modules目录下的 UTS 插件模块其目录结构如下src/uni_modules/uts-worker-sendable-transfer/ ├── utssdk/ │ ├── index.uts # 插件主实现UTSSendableWorkerImpl 类 │ ├── interface.uts # 对外暴露的类型定义 │ └── sendable.ets # HarmonyOS Sendable 标记的可共享对象 ├── changelog.md # 更新日志当前为空 ├── package.json # 插件元信息与平台支持声明 └── readme.md # 开发文档入口从 package.json 可以看到该插件的工程约束类型为utsdcloudext.type要求 HBuilderX^3.6.8、uni-app / uni-app-x^3.1.0且为免费插件price: 0.00。该模块解决的核心问题是当主线程与 Worker 线程之间需要传递较大数据如 ArrayBuffer 二进制或共享对象时默认的结构化克隆/序列化拷贝开销大、耗时长。为此插件对外提供两种平台级的高效通道HarmonyOSSendable 对象通过postMessageWithSharedSendable实现共享引用传输避免拷贝WebTransferable 对象通过所有权转移传输 ArrayBuffer 等转移后原缓冲区长度变为 0。从源码结构看index.uts插件对外只暴露一个核心类UTSSendableWorkerImpl内部持有Worker实例与消息监听回调封装了创建—发送—监听—销毁的完整生命周期。核心类型定义与 API 说明插件通过 interface.uts 对外暴露全部类型并在 index.uts 中通过export *一并转发类型说明关键字段UTSWorkerAddListenerOptions添加消息监听的入参success?: UTSWorkerReceiveEventCallbackUTSWorkerAddListenerOptionsSuccess消息回调的结果对象result: UTSJSONObjectUTSWorkerSendWorkerMessageOptions发送消息的入参message: Object、harmonySendable?: boolean、transfer?: ArrayBuffer[]UTSWorkerReceiveEventCallback接收回调函数类型(callback: UTSWorkerAddListenerOptionsSuccess) voidUTSSendableWorkerImpl插件主类create()/sendMessage()/onMessage()/destroy()其中发送参数的三个字段含义如下message要发送给 Worker 的数据任意ObjectharmonySendable是否将消息包装为符合 Sendable 协议的对象发送仅鸿蒙生效默认不开启即走普通序列化拷贝transfer可转移的ArrayBuffer[]数组转移后主线程侧原缓冲区被掏空Web 平台表现明显byteLength变为 0。UTSSendableWorkerImpl 生命周期方法create()负责创建 Worker。源码index.uts中先检查是否已有实例若已存在会打印告警并先销毁旧实例随后调用uni.createWorker(workers/sendableTransferWorker.uts)创建指向src/workers/下 Worker 脚本的实例。这保证了单例语义避免重复创建造成资源泄漏。sendMessage()的发送逻辑index.uts值得展开当harmonySendable为真且处于APP-HARMONY条件编译分支时消息会被替换为 sendable.ets 中定义的SendableObject实例——这是一个用Sendable注解标记的 ArkTS 类字段a: number 45会被作为共享数据传给 Worker随后调用worker.postMessage(message, { harmonySendable, transfer })完成真正发送。onMessage()注册监听index.uts内部调用底层worker.onMessage收到消息后把原始结果包装为UTSWorkerAddListenerOptionsSuccessresult为UTSJSONObject再回调给用户。destroy()负责清理index.uts调用worker.terminate()结束 Worker 线程并置空内部引用与回调避免悬挂引用。与底层 uni.createWorker API 的对应关系该插件是底层uni.createWorker能力uni-createWorker 模块的上层封装。在 uni-createWorker 的类型定义 中Worker.postMessage的WorkerPostMessageOptions与插件参数一一对应harmonySendable?: boolean——注释明确说明是否支持符合 Sendable 协议的对象作为共享变量发送使用 postMessageWithSharedSendable 实现默认值为 false仅鸿蒙平台支持unixVer 4.81、unixVaporVer 5.0 起transfer?: any[]——可转移对象数组默认值为空数组仅鸿蒙、web 平台支持web 端 unixVer 4.81 起。也就是说插件在鸿蒙端通过postMessageWithSharedSendable走共享引用通道在 Web 端通过 Transferable objects 走所有权转移通道而在 Android、iOS 等平台这些参数被忽略退化为常规序列化传输。此外底层 Worker 接口 还提供了envWorker 内环境变量如USER_DATA_PATH、onError错误监听与terminate()。与 Worker 相关的错误码也定义在同文件中interface.uts5000501Worker 运行错误、5000502序列化失败、5000503实例未运行、5000504Worker 线程中不支持调用的 API、5000505初始化失败、5000506文件路径无效、5000510非主线程调用、5000511Worker 线程无效便于开发者在onError中做精细化排障。完整实战在页面中接入该插件仓库在 worker-sendable-transfer.uvue 提供了完整可运行的演示页面接入步骤清晰1. 引入插件并实例化import { UTSWorkerAddListenerOptions, UTSWorkerReceiveEventCallback, UTSWorkerSendWorkerMessageOptions, UTSSendableWorkerImpl } from /uni_modules/uts-worker-sendable-transfer; const sendableWorker new UTSSendableWorkerImpl()页面同时准备了一个 8 字节的ArrayBuffer作为二进制传输样本const myBuf ref(new ArrayBuffer(8)) const data reactive({ myBufLength: -1, sendableNumber: 0, } as DataType)2. 创建 Worker 并注册消息监听function create() { sendableWorker.create() workerStatus.value created; // 添加消息监听 sendableWorker.onMessage({ success: (res) { const result res.result; // #ifdef APP-HARMONY // 这里经过 worker 修改后result.a 应该是 666 data.sendableNumber result.a // #endif addLog(收到WorkerTask返回: ${JSON.stringify(result)}, receive); } }); }3. 发送消息Sendable Transferable 双通道function sendMessage() { data.myBufLength myBuf.value.byteLength sendableWorker.sendMessage({ message: 这里是主线程发送的 message, harmonySendable: true, transfer: [myBuf.value] }) // NOTE: HarmonyOS 长度不变web 长度变为 0 data.myBufLength myBuf.value.byteLength }发送后再次读取myBuf.byteLength在HarmonyOS 上长度保持不变Sendable 共享引用不搬移缓冲区而在Web 上长度变为 0Transferable 把ArrayBuffer所有权转移给了 Worker。4. 页面卸载时销毁onUnload(() { destory(); }) function destory() { sendableWorker.destroy() workerStatus.value destroyed; }Worker 端脚本实现Worker 线程脚本位于 sendableTransferWorker.uts继承WorkerTaskImpl并实现两个钩子entry()Worker 启动入口打印初始化日志onMessage(message)接收主线程消息。在APP-HARMONY分支下若检测到消息是带数字字段a的对象就把它改写为666然后postMessage原样回发从而验证 Sendable 对象是共享引用——Worker 的修改主线程直接可见。export class SendableTransferWorker extends WorkerTaskImpl { override entry() { console.log([WorkerTask] HelloWorkerTask 启动完成等待主线程消息); } override onMessage(message : any) { // #ifdef APP-HARMONY if (typeof message object typeof (message as ESObject).a number) { (message as ESObject).a 666 } // #endif this.sendReply(message); } }自动化测试验证跨平台行为差异仓库在 worker-sendable-transfer.test.js 中对该能力做了端到端自动化测试测试只对harmony与web两个平台生效其余平台直接跳过流程为program.reLaunch打开演示页并等待 500ms调用页面暴露的create方法创建 Worker调用sendMessage发送消息断言两个关键数据data.myBufLengthHarmonyOS 上期望为 8缓冲区未被转移Web 上期望为 0缓冲区所有权已转移data.sendableNumberHarmonyOS 上期望为 666Sendable 对象被 Worker 修改后共享可见。这两个断言恰好从测试层面印证了上文所述的平台差异可作为回归用例持续守护该能力。使用注意事项与平台差异小结综合源码与测试使用该插件时需注意以下几点平台适用性harmonySendable仅鸿蒙uni-app-x 4.81 / Vapor 5.0 起支持transfer仅鸿蒙与 Web 支持Android、iOS 及小程序端不受影响参数被忽略。transfer的副作用在 Web 端ArrayBuffer被转移后主线程原引用byteLength变为 0若仍需在主线程使用该缓冲请先拷贝或提前读取鸿蒙端因 Sendable 是共享引用长度不变。生命周期管理create()具备先销毁旧实例再创建的幂等保护务必在页面onUnload中调用destroy()释放 Worker 线程避免后台常驻线程导致内存问题。条件编译SendableObject仅存在于APP-HARMONY分支index.uts其他平台编译时会自动剔除相关代码演示页面中result.a的读取同样放在#ifdef APP-HARMONY内。Worker 脚本路径uni.createWorker(workers/sendableTransferWorker.uts)指向src/workers/目录若在自有项目中使用请按实际目录放置脚本。相关学习资源该插件 readme 中指向的 UTS 开发资料在仓库docs目录下均有对应文档可供查阅UTS 语法总览docs/uts/README.mdUTS 插件开发含插件结构、manifest 配置docs/plugin/uts-plugin.mduni-app 兼容模式下使用 UTS 组件docs/plugin/uts-component.md标准模式uni-app-xUTS 组件docs/plugin/uts-component-vue.md各平台原生能力接入docs/plugin/uts-for-android.md、docs/plugin/uts-for-ios.md、docs/plugin/uts-for-harmony.md官方示例工程 Hello UTS 的仓库内镜像examples/hello-uts以及对应的 uni-app-x 版示例 examples/hello-uvue总结uts-worker-sendable-transfer是 uni-app 仓库中一个结构精简但功能定位明确的 UTS 插件它以UTSSendableWorkerImpl类封装 Worker 全生命周期把 HarmonyOS 的 Sendable 共享引用传输与 Web 的 Transferable 所有权转移统一到sendMessage的两个参数之下配合条件编译实现对多端的一致 API 与差异化的底层传输策略。开发者可直接将src/uni_modules/uts-worker-sendable-transfer目录复制进自己的uni_modules参考src/pages/API/create-worker/worker-sendable-transfer.uvue的接入方式快速落地并使用仓库中已有的自动化测试用例保障跨平台行为正确性。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
