更新记录

1.1.0（2026-01-13） 下载此版本

功能优化, 入参有变动, 更新插件请注意

1.0.7（2025-11-27） 下载此版本

优化

1.0.6（2025-06-27） 下载此版本

更新文档

平台兼容性

uni-app(4.0)

说明文档

概述

websocket 模块对 uni-app WebSocket 能力做了轻量封装，提供连接初始化、消息收发、心跳保活、断线重连、关闭连接等能力，并对业务侧屏蔽部分底层细节（如 ping/pong 过滤、重连上限通知等）。

适用范围

• uni-app 运行环境（依赖 uni.connectSocket / socketTask.* / uni.closeSocket 等接口）。
• 单连接场景（一个 MyWebSocket 实例维护一个 socket 连接）。

功能说明

1) 消息模型 Message

用于约定消息体结构：

• event: string：事件类型
• data: any：业务载荷（可选）

心跳消息默认发送 event = "ping"。

2) WebSocket 封装 MyWebSocket

核心能力：

• 连接管理：init() 建立连接，避免重复初始化；连接成功后自动启动心跳。
• 消息接收：仅对 string 类型数据进行 JSON.parse，并过滤 event === "ping" / "pong"，其余消息才回调给业务 onMessage。
• 消息发送：默认要求发送对象是 Message 实例（可关闭校验）。
• 心跳：按间隔持续发送 ping；若发现未连接，触发重连逻辑。
• 重连：断线/错误时自动重连；达到最大次数后停止并触发 onReconnectFail（仅一次，连接成功后重置）。
• 关闭：主动关闭会阻止后续重连，并清理心跳/重连定时器。

API 说明

导出项

• Message
• MyWebSocket

类型定义

MyWebSocketCtorOptions（构造参数）

类：Message

构造函数

new Message(event, data)

类：MyWebSocket

构造函数

new MyWebSocket(options)

参数校验

• onMessage 必须为函数，否则抛错。
• onReconnectFail 若传入则必须为函数，否则抛错。

方法：init

初始化连接（若不传 options，优先使用构造时 connectOptions / 上次缓存的 options）。

ws.init(options?, type?)
// type: 'init' | 'reconnect'

返回值

• Promise：连接成功 resolve(onOpen res)；失败时 reject(error)。

行为要点

• 已连接时直接 resolve()，避免重复初始化。
• 连接成功后：connected=true、重连计数清零、重连失败通知标记重置、启动心跳。
• onError/onClose 会触发 reconnect()。

方法：send

发送消息。

ws.send(message, verifyFormat?)

返回值

• Promise：调用 socketTask.send，成功 resolve，失败 reject。

方法：heartbeat

启动/重置心跳定时器，周期发送 new Message('ping')。

ws.heartbeat()

行为要点

• 每次调用会清理旧的心跳定时器并重新设置。
• 定时触发时：若已连接则发送 ping；否则触发 reconnect()。

方法：reconnect

断线重连逻辑。

ws.reconnect()

行为要点

• 若 closeFlag === true（主动关闭）则不再重连。
• 达到 reconnectMaxTimes 后停止重连，并触发一次 onReconnectFail({times,maxTimes,options})。
• 每次重连：延迟 reconnectDelayTime 后调用 init(this.options, 'reconnect')，并累计次数。

方法：close

主动关闭连接（并阻止后续重连）。

ws.close(options?)

返回值

• Promise：关闭成功 resolve，失败 reject。

行为要点

• 设置 closeFlag = true，清理心跳与重连定时器。
• 若当前未连接会直接 reject('WebSocket 连接未开启')。

消息处理约定

接收

• 仅当 data 为字符串时尝试 JSON.parse。解析失败会记录日志但不中断流程。
• 过滤 event === 'ping' / 'pong'，其余消息才回调 onMessage(message)。
• ArrayBuffer 分支预留（当前未实现具体处理）。

发送

• 默认要求 Message 实例，模块内部会 JSON.stringify(message) 后发送。

使用示例

import { MyWebSocket, Message } from '@/uni_modules/x-web-socket/js_sdk/index.js'

const ws = new MyWebSocket({
  onMessage: (msg) => {
    // 这里拿到的是业务消息（已过滤 ping/pong）
    console.log('biz msg:', msg)
  },
  connectOptions: {
    url: 'wss://example.com/ws',
    // 其他 uni.connectSocket 参数可继续透传
  },
  onReconnectFail: ({ times, maxTimes }) => {
    console.warn(`reconnect failed: ${times}/${maxTimes}`)
  }
})

// 初始化连接
ws.init() // 可传入带token的url

// 发送业务消息
ws.send(new Message('chat.send', { text: 'hello' }))

// 主动关闭（不会再自动重连）
ws.close()

异常与边界情况

• 构造参数错误：onMessage 非函数直接抛错；onReconnectFail 若传入但非函数也会抛错。
• 重复 init：已连接时会跳过初始化并直接 resolve()。
• 缺失/非法 url：options.url 非字符串会 reject('options.url 应该是一个字符串')。
• 未连接发送：send() 在未连接状态会 reject('WebSocket 连接未开启')。
• 消息格式校验：默认要求 Message 实例，否则 reject('消息格式错误')；可通过 verifyFormat=false 放宽。
• 消息解析失败：接收字符串但 JSON 解析失败会捕获异常并记录日志，不会抛出到业务层。
• 重连上限：达到 reconnectMaxTimes 后停止重连，并只通知一次；后续即使继续触发断线也不会重复回调，直到再次连接成功重置标记。
• 主动关闭：close() 会设置 closeFlag=true，从而阻止任何后续自动重连。

依赖关系

• 外部库依赖：无（仅依赖 uni-app 运行时 WebSocket API）。

插件如果对你有帮助给个好评吧~