示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载导读uni-websocket是 uni-app / uni-app x 生态中一个以 UTS 插件形态交付的 WebSocket 连接管理模块通过同一套uni.connectSocket、uni.sendSocketMessage、uni.closeSocket等 API 屏蔽了 AndroidKotlin、iOSSwift、HarmonyOSArkTS三端底层实现的差异。本文以仓库中的 模块 readme 为骨架结合 接口声明 与各平台实现源码完整讲解 UTS 语言与 UTS 插件的基本机制、模块提供的全部 WebSocket API 与参数语义、三端底层实现原理、错误码体系并给出可直接落地的连接、收发、关闭与监听完整代码示例帮助读者既会用 API也看得懂其底层是如何做到一套代码多端运行的。一、模块概览一个UTS 插件形态的 WebSocket 连接管理模块按仓库内 readme 的定义uni-websocket模块的职责一句话概括为实现 WebSocket 连接管理功能。它不是一个普通的 JS 组件而是一个典型的UTS 插件——即使用 UTS 语言编写的 uni_modules 插件其核心目的是允许 uni-app / uni-app x 开发者使用 UTS 语法来调用扩展 API封装原生系统的 API 或三方 SDK。从 package.json 可以确认该插件的元信息id/displayNameuni-websocket版本1.0.0engines.HBuilderX要求^3.6.8及以上版本dcloudext.typeuts即这是一个 UTS 类型插件dcloudext.saleregular 与 sourcecode 价格均为0.00即免费开源插件uni_modules.platforms在客户端侧覆盖 Vuevue2/vue3、Appapp-android / app-ios、H5 与各大小程序平台属于全平台型插件。值得关注的是uni_modules[uni-ext-api]一节它向 uni-app 框架声明了本插件注入到uni.命名空间下的 7 个扩展 API并且对 App 三端kotlin / swift / arkts均标记为true| 声明 API | App-Android (kotlin) | App-iOS (swift) | App-Harmony (arkts) | | -- | -- | -- | -- | |connectSocket| true | true | true | |sendSocketMessage| true | true | true | |closeSocket| true | true | true | |onSocketOpen| true | true | true | |onSocketMessage| true | true | true | |onSocketClose| true | true | true | |onSocketError| true | true | true |也就是说插件一旦被工程引入开发者即可在 App 三端直接调用这些uni.xxx全局 API无需关心底层是 OkHttp 还是 Starscream。二、地基UTS 语言是什么、为什么能跨端要理解uni-websocket为什么能做到一份源码跑三端原生必须先理解其编写语言 UTS。readme 中给出了权威说明这里结合仓库实践展开UTSuni type script是一门跨平台的、高性能的、强类型的现代编程语言。它可以被编译为不同平台的编程语言| 目标平台 | 编译产物语言 | | -- | -- | | Android | Kotlin | | iOS | Swift | | HarmonyOS鸿蒙 | ArkTS | | Web / 小程序 | JavaScript |UTS 采用了与 TypeScript 基本一致的语法规范并支持绝大部分 ES6 API但为了跨端UTS 做了一些约束和特定平台的增补。过去在 JS 引擎下运行支持的语法大部分在 UTS 的处理下也可以平滑地在 Kotlin 和 Swift 中使用但有些能力无法抹平此时需要使用条件编译。与 uni-app 的条件编译类似UTS 也支持条件编译——写在条件编译块里的代码可以调用平台特有的扩展语法。在uni-websocket源码中就可以看到这种写法的实际应用例如 unierror.uts 中export class ConnectSocketFailImpl extends UniError implements ConnectSocketFail { // #ifdef APP-ANDROID override errCode: ConnectSocketErrorCode // #endif constructor(errCode : ConnectSocketErrorCode) { super(); this.errSubject UniWebsocketErrorSubject; this.errCode errCode; this.errMsg ConnectUniErrors[errCode] ?? } }// #ifdef APP-ANDROID与// #endif之间的override声明只会在 Android 平台参与编译iOS / HarmonyOS 编译时会被剔除这正是 UTS 条件编译抹平平台差异的直观例证。仓库内还提供了 uts 与 ts 的差异文档、UTS 语言官方文档 等资料需要系统学习 UTS 的读者可继续查阅。三、UTS 插件机制utssdk 目录如何按平台组织代码readme 明确指出UTS 插件的实现代码主要位于utssdk目录下并按平台进行分离和组织。原文档中的目录说明表是理解该插件目录结构的钥匙完整继承如下| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS, Kotlin, Java | 存放 UTS 插件在 Android 平台上的具体实现源码 | |utssdk/app-ios| iOS | UTS, Swift | 存放 UTS 插件在 iOS 平台上的具体实现源码 | |utssdk/app-harmony| HarmonyOS (鸿蒙) | UTS, ArkTS | 存放 UTS 插件在 HarmonyOS 平台上的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 存放使用 UTS 语言编写的、可供所有平台共用的实现源码 |对照仓库中uni-websocket插件的实际文件树这张表完全成立src/uni_modules/uni-websocket/ ├── package.json # 插件元信息与 uni-ext-api 声明 ├── readme.md # 模块说明文档 ├── changelog.md # 更新日志 └── utssdk/ ├── interface.uts # 公共全部 API 与类型的声明 ├── interface.type.uts # 公共SocketDataOptionsstring | ArrayBuffer ├── protocol.uts # 公共参数协议校验 ├── unierror.uts # 公共UniError 错误对象与错误码映射 ├── app-android/ │ ├── index.uts # Android 平台导出实现 │ ├── config.json # Android 原生依赖配置 │ └── websocket/ │ ├── WebSocketManager.uts │ └── WebsockerClient.uts ├── app-ios/ │ ├── index.uts # iOS 平台导出实现 │ ├── config.json │ └── frameworks/ # Starscream.xcframework、websocket.xcframework │ └── websocket/ # iOS 侧 WebSocketManager.uts / WebsockerClient.uts └── app-harmony/ └── index.uts # HarmonyOS 平台导出实现这里可以总结出 UTS 插件的三条约定读者开发自己的 UTS 插件时可复用公共逻辑下沉到utssdk/*.uts类型声明、协议校验、错误定义等跨平台共享内容放在 utssdk 根目录三端共用平台实现按目录隔离app-android、app-ios、app-harmony三个子目录分别放置各自平台的实现互不干扰每平台入口是index.uts平台目录下的index.uts负责对外导出该平台的 API 实现uni-app 编译器按目标平台自动选择对应目录。3.1 平台原生依赖的声明方式原生依赖放在各平台目录下的config.json中例如 app-android/config.json{ dependencies: [ com.squareup.okhttp3:okhttp:3.12.12 ], minSdkVersion: 19 }这说明 Android 平台实现基于 OkHttp 3.12.12并声明了最低支持的minSdkVersion为 19Android 4.4。而 iOS 平台则通过frameworks/目录内置了Starscream一款纯 Swift 实现的 WebSocket 客户端库的 xcframework分别提供真机ios-arm64与模拟器ios-arm64_x86_64-simulator两个分片——这是 UTS 插件混编原生语言/三方 SDK的标准做法相关规范可参考仓库内的 uts 插件原生语言混编开发文档。四、WebSocket API 全貌7 个全局 API SocketTask 对象uni-websocket的全部接口形态定义在公共文件 interface.uts 中。它声明了两类能力全局 APIuni.前缀调用共 7 个SocketTask 对象uni.connectSocket的返回值提供 6 个方法。4.1 全局 API 一览| API | 签名 | 说明 | | -- | -- | -- | |uni.connectSocket(options)|(options: ConnectSocketOptions) SocketTask| 创建 WebSocket 连接返回 SocketTask | |uni.onSocketOpen(callback)|(result: OnSocketOpenCallbackResult) void| 监听连接打开事件已废弃用 SocketTask 的 onOpen 替换 | |uni.onSocketMessage(callback)|(result: OnSocketMessageCallbackResult) void| 监听收到服务器消息已废弃用 onMessage 替换 | |uni.sendSocketMessage(options)|(options: SendSocketMessageOptions) void| 通过连接发送数据已废弃用 SocketTask 的 send 替换 | |uni.onSocketError(callback)|(result: OnSocketErrorCallbackResult) void| 监听连接错误已废弃用 onError 替换 | |uni.closeSocket(options)|(options: CloseSocketOptions) void| 关闭连接已废弃用 SocketTask 的 close 替换 | |uni.onSocketClose(callback)|(result: OnSocketCloseCallbackResult) void| 监听连接关闭已废弃用 onClose 替换 |接口注释中明确标注除connectSocket外的 6 个全局 API 均已废弃deprecated官方推荐的新用法是先uni.connectSocket拿到SocketTask再通过 task 的onOpen / onMessage / send / close / onError / onClose管理本次连接。旧式全局 API 仍可用但会作用于最近一次创建的连接见下文源码分析。4.2ConnectSocketOptions参数详解connectSocket的入参类型定义在 interface.uts各字段语义如下| 参数 | 类型 | 必填 | 默认值 | 说明 | | -- | -- | -- | -- | -- | |url|string| 是 | - | 开发者服务器接口地址 | |header|UTSJSONObject \| null| 否 |null| HTTP 请求 Headerheader 中不能设置 Referer| |protocols|string[] \| null| 否 |null| 子协议数组WebSocket Subprotocol | |success|(result: ConnectSocketSuccess) void \| null| 否 |null| 调用成功的回调 | |fail|(result: ConnectSocketFail) void \| null| 否 |null| 调用失败的回调 | |complete|(result: any) void \| null| 否 |null| 调用结束成功、失败都会执行的回调 |对应的参数协议校验在 protocol.uts 中实现export const ConnectSocketApiProtocol new Mapstring, ProtocolOptions([ [ url, { type: string, required: true } ], [ header, { type: object, required: false } ], [ protocols,{ type: string[],required: false } ], ]); export const ConnectSocketApiOptions: ApiOptionsConnectSocketOptions { formatArgs: new Mapstring, Function([ [ url, function (url: string, params: ConnectSocketOptions) { if (url null) { throw new Error(url is required) } } ] ]), }即url为必填字符串缺失时直接抛出url is requiredheader必须是对象protocols必须是字符串数组。4.3SendSocketMessageOptions参数详解export type SendSocketMessageOptions { data: any, // 需要发送的内容app 平台从 4.61 版本开始支持 ArrayBuffer success?: ((result: GeneralCallbackResult) void) | null, fail?: ((result: SendSocketMessageFail) void) | null, complete?: ((result: any) void) | null };data的类型在 interface.type.uts 中定义为SocketDataOptionsexport type SocketDataOptions String | ArrayBuffer;即支持发送字符串与ArrayBuffer二进制两种数据其中 app 平台从 4.61 版本开始支持ArrayBuffer该版本信息同时标注于 interface.uts 的注释中。4.4CloseSocketOptions参数详解export type CloseSocketOptions { code?: number | null, // 关闭连接的状态号默认 1000表示正常连接关闭 reason?: string | null, // 可读的关闭原因必须是不长于 123 字节的 UTF-8 文本不是字符 success?: ..., fail?: ..., complete?: ... };需要注意两个约束code未指定时默认取值1000正常关闭reason是最多 123 字节的 UTF-8 文本且以字节数而非字符数计量中文等多字节字符要特别留意。4.5 SocketTask 对象connectSocket返回的SocketTask定义于 interface.uts是对单条连接的操作句柄提供| 方法 | 说明 | | -- | -- | |send(options: SendSocketMessageOptions)| 通过该连接发送数据 | |close(options: CloseSocketOptions)| 关闭该连接 | |onOpen(callback)| 监听该连接打开事件回调参数含header连接成功的 HTTP 响应 Header | |onClose(callback)| 监听该连接关闭回调参数含code关闭状态号与reason关闭原因 | |onError(callback)| 监听该连接错误回调参数含errMsg| |onMessage(callback)| 监听该连接收到服务器消息回调参数含dataapp 4.61 起可为 ArrayBuffer |监听回调的类型细节如OnSocketOpenCallbackResult.header、OnSocketCloseCallbackResult.code/reason、OnSocketMessageCallbackResult.data均可在上述文件对应位置找到完整注释这里不再赘述。五、三端源码实现单例管理 平台客户端5.1 AndroidWebSocketManager 单例 OkHttp 客户端Android 平台的入口 app-android/index.uts 非常薄7 个 API 全部委托给WebSocketManager单例export const connectSocket : ConnectSocket (options : ConnectSocketOptions) : SocketTask { return WebSocketManager.getInstance().connectSocket(options); } export const sendSocketMessage : SendSocketMessage (options : SendSocketMessageOptions) : void { return WebSocketManager.getInstance().sendSocketMessage(options); } // ... onSocketOpen / onSocketMessage / onSocketClose / onSocketError 同理WebSocketManager.uts 内部是一个经典的单例管理器核心数据结构有两组socketTasks: SocketTask[]保存所有连接任务。源码注释明确说明当 uni. 开头调用的时候只作用于 0 元素这个 task 数组当 error 或者 close 的时候会删除——这就是旧式全局 API 作用于最近一次连接的源码级依据L112-L113taskMap: MapWebsockerClient, SocketTask维护底层客户端对象与任务对象的绑定关系用于回调事件反查对应 task。connectSocket的调用链为L137-L151创建WebsockerClient封装 OkHttp 的 WebSocket包装为SimpleSocketTask并注册进socketTasks与taskMap立即回调successerrMsg: connectSocket:ok与complete调用webscoketClient.connect()发起真实连接返回 task 给调用方。SimpleSocketTaskL4-L97) 实现了SocketTask接口内部维护 open / close / error / message 四类回调数组并提供dispatchXxx方法供底层客户端事件统一派发send/close在底层客户端为空时连接已失效会构造错误结果并依次回调fail与complete。事件回调onOpen/onMessage/onClose/onError的统一处理逻辑为以onClose为例L239-L261通过taskMap反查 task若该 task 是socketTasks[0]且全局回调已注册则同时触发全局onSocketClose将 task 从socketTasks中移除并从taskMap中删除绑定向 task 自身的onClose回调派发{ code, reason }。从源码结构可以推断该设计既兼容了旧的全局uni.onSocketXxx监听方式也保证了基于 SocketTask 的多连接场景下各连接事件互不串扰。5.2 iOS基于 Starscream 的同一套 Manager 结构iOS 平台目录utssdk/app-ios下同样存在WebSocketManager.uts/WebsockerClient.uts以及入口index.uts并内置了Starscream.xcframework与封装好的websocket.xcframework分别提供真机与模拟器架构的二进制分片。可以推断 iOS 实现沿用了与 Android 相同的 Manager Client 架构仅将底层网络库替换为 Starscream。UTS 在此平台会被编译为 SwiftStarscream 正是以 Swift 编写的主流 WebSocket 客户端库这也与 readme 中iOS 平台编译为 Swift的描述一致。5.3 HarmonyOS独立入口 index.utsutssdk/app-harmony目录下有独立的index.uts入口UTS 在此平台编译为 ArkTS说明鸿蒙侧拥有独立的 WebSocket 实现路径无需依赖 Android / iOS 的网络栈。鸿蒙平台 UTS 插件开发注意事项可参考仓库内的 uts 插件 HarmonyOS 平台开发注意事项。六、错误码体系Connect 与 Send 的 4 个错误码公共文件 unierror.uts 集中定义了错误主题与错误码映射连接类错误ConnectSocketErrorCode| 错误码 | 说明 | 错误消息errMsg | | -- | -- | -- | |600009| URL 格式不合法 |invalid URL|发送类错误SendSocketMessageErrorCode| 错误码 | 说明 | 错误消息errMsg | | -- | -- | -- | |10001| 发送数据超限发送队列不能超过 16M 大小 |The queue memory exceeds 16 MiB and the connection will be closed| |10002| websocket 未连接 |webSocket is not connected| |602001| websocket 系统错误 |websocket system error|对应的失败对象ConnectSocketFailImpl/SendSocketMessageFailImpl均继承自UniError构造函数中会设置errSubject uni-websocket、errCode与errMsgL39-L61。其中errMsg的英文文案The queue memory exceeds 16 MiB...提示了一个重要的工程事实单连接发送队列上限为 16 MiB超限会直接关闭连接因此高频推送场景务必控制发送速率与单条消息体积。另外在 WebSocketManager.uts 中closeSocket在未建立连接时返回的错误消息为closeSocket:fail WebSocket is not connectedL173-L175send在未连接时则构造errCode 10002的失败对象L50两者可在业务侧作为是否已连接的兜底判断。七、实战完整可运行的 WebSocket 使用示例7.1 推荐用法基于 SocketTask这是官方推荐的新式用法接口注释中的 example 即为此形态见 interface.uts// 1. 创建连接 const task uni.connectSocket({ url: ws://192.168.12.106:8080/ws, complete: (e) { console.log(socket :, e); } }); // 2. 监听连接打开 task.onOpen((res) { console.log(WebSocket连接已打开, res.header); }); // 3. 监听服务器消息app 4.61 起 res.data 可为 string 或 ArrayBuffer task.onMessage((res) { console.log(收到服务器内容 res.data); }); // 4. 监听错误与关闭 task.onError((res) { console.log(WebSocket错误, res.errMsg); }); task.onClose((res) { console.log(WebSocket 已关闭code res.code reason res.reason); }); // 5. 发送数据需在连接打开之后 task.send({ data: halo }); // 发送二进制数据app 4.61 task.send({ data: arrayBuffer }); // 6. 关闭连接code 默认 1000 正常关闭 task.close({ code: 1000, reason: bye });7.2 兼容用法全局 API已废弃接口注释中保留了旧式全局 API 的完整示例形态interface.utsuni.onSocketOpen(function (res) { console.log(WebSocket连接已打开); }); uni.onSocketError(function (res) { console.log(WebSocket连接打开失败请检查); }); uni.sendSocketMessage({ data: msg }); uni.onSocketMessage(function (res) { console.log(收到服务器内容 res.data); }); uni.closeSocket(); uni.onSocketClose(function (res) { console.log(WebSocket 已关闭); });注意全局 API 只作用于最近一次创建的连接源码见 WebSocketManager.uts 中始终取socketTasks[0]的逻辑因此多连接场景请务必使用 SocketTask 形态避免事件串线。7.3 工程接入与版本前提将uni-websocket作为 uni_modules 插件引入工程后uni.connectSocket等 API 即可在 App 三端使用H5 / 小程序端则由 uni-app 框架自身能力提供无需本插件package.json 中uni-ext-api仅声明 app 平台 kotlin / swift / arkts 为 true。版本前提HBuilderX^3.6.8App 端ArrayBuffer收发需 uni-app x 4.61 及以上鸿蒙侧 uniVer 4.23 / unixVer 4.61 起可用版本标注见 interface.uts 中各 API 的 uniPlatform 注释。Android 端最低支持 Android 4.4minSdkVersion 19。八、使用注意事项与最佳实践综合接口注释与源码总结以下工程要点优先使用 SocketTask 而非全局 API6 个uni.onSocketXxx/uni.sendSocketMessage/uni.closeSocket均已标记废弃且只作用于最近连接SocketTask 形态支持多连接隔离。发送时机发送数据必须在连接打开onOpen回调触发之后进行未连接时send会以errCode 10002webSocket is not connected回调fail。发送队列上限 16 MiB超过 16 MiB 会触发10001错误并关闭连接需控制消息大小与频率。header 限制header中不能设置Referer。关闭参数约束code默认 1000reason为不超过123 字节的 UTF-8 文本。URL 校验url必填格式不合法时返回错误码600009invalid URL。连接生命周期连接 error 或 close 后任务会从管理器的socketTasks数组中移除见 WebSocketManager.uts如需重连需重新调用connectSocket可结合onClose/onError实现指数退避的重连策略。二进制支持收发ArrayBuffer二进制帧需要 app 4.61做即时通讯的图片 / 音频上行场景可直接使用。九、延伸阅读模块本体uni-websocket readme、package.json接口与类型interface.uts、interface.type.uts参数协议与错误protocol.uts、unierror.utsAndroid 实现app-android/index.uts、WebSocketManager.uts官方 API 文档WebSocket 全局 API 文档、WebSocket API 文档UTS 相关UTS 语言介绍、uts 和 ts 的差异、uts 插件开发文档、uts 插件原生语言混编开发文档、uts 插件 Android 平台开发注意事项、uts 插件 iOS 平台开发注意事项、uts 插件 HarmonyOS 平台开发注意事项赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-route 页面路由管理 UTS 插件uni-app x 跨端路由 API 的架构与源码解析uni route 页面路由管理 UTS 插件uni app x 跨端路由 API 的架构与源码解析 uni route 是 uni app 仓库中以 uni示例工程前端移动开发跨平台uni-app x 腾讯定位 UTS 插件 uni-location-tencent 接入指南与源码解析uni app x 腾讯定位 UTS 插件 uni location tencent 接入指南与源码解析 本文以 uni app 开源仓库中的 uni loca示例工程前端移动开发跨平台uni-app 中的 uni-navigationBar UTS 插件导航栏 API 的跨端实现与源码解析uni app 中的 uni navigationBar UTS 插件导航栏 API 的跨端实现与源码解析 uni navigationBar 是 uni a示例工程前端移动开发跨平台上一篇PyCryptoBot风险管理完全指南止损、追踪止损与资金保护策略下一篇告别混乱标签Kaniko构建镜像的环境与版本标识最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考