JoyD/Web/Vue/CubeLib/docs/CubeWebSocket.md

CubeWebSocket

一个功能完善的 WebSocket 组件，支持自动连接、重连、消息队列、心跳机制等功能。

基础用法

<template>
  <div>
    <div>状态: {{ status }}</div>
    <div>消息数量: {{ messages.length }}</div>
    <CubeWebSocket
      ws-url="ws://localhost:8086/ws"
      :auto-connect="true"
      :reconnect="true"
      :debug-mode="true"
      @connected="handleConnected"
      @disconnected="handleDisconnected"
      @message="handleMessage"
      @status-changed="handleStatusChanged"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import CubeWebSocket from 'joyd.web.vue.cubelib'

const status = ref('disconnected')
const messages = ref([])

const handleConnected = () => {
  console.log('WebSocket 已连接')
  status.value = 'connected'
}

const handleDisconnected = (code, reason) => {
  console.log('WebSocket 已断开:', code, reason)
  status.value = 'disconnected'
}

const handleMessage = (message) => {
  console.log('收到消息:', message)
  messages.value.push(message)
}

const handleStatusChanged = (newStatus) => {
  console.log('状态变化:', newStatus)
  status.value = newStatus
}
</script>

Props

参数	说明	类型	默认值	必填
wsUrl	WebSocket 服务器地址	String	''	否
autoConnect	是否自动连接	Boolean	true	否
reconnect	是否自动重连	Boolean	true	否
maxReconnectDelay	最大重连延迟（毫秒）	Number	30000	否
debugMode	是否开启调试模式	Boolean	false	否
heartbeatInterval	心跳间隔（毫秒）	Number	30000	否
connectTimeout	连接超时（毫秒）	Number	10000	否
maxQueueSize	消息队列最大长度	Number	100	否

Props 说明

wsUrl

WebSocket 服务器的完整 URL 地址。如果为空字符串，则使用默认值 ws://localhost:8086/ws。

验证规则：如果提供值，必须是有效的 URL 格式。

autoConnect

组件挂载时是否自动连接到 WebSocket 服务器。

reconnect

连接断开后是否自动重连。重连使用指数退避策略，延迟从 1 秒开始，每次失败后翻倍，最大不超过 maxReconnectDelay。

maxReconnectDelay

重连的最大延迟时间（毫秒）。默认为 30 秒。

debugMode

是否开启调试模式。开启后会在控制台输出详细的日志信息，包括：

• 连接状态变化
• 消息发送和接收
• 错误信息
• 定时器状态

heartbeatInterval

心跳检测的间隔时间（毫秒）。连接成功后会定期发送 ping 消息以保持连接活跃。

connectTimeout

连接超时时间（毫秒）。如果在指定时间内连接未建立，将自动关闭连接并触发 error 事件。

maxQueueSize

消息队列的最大长度。当连接未建立时，发送的消息会被加入队列。如果队列已满，新消息将被丢弃并触发 message-failed 事件。

Events

事件名	说明	参数
connected	连接成功	-
disconnected	连接断开	(code, reason)
error	连接错误	error
message	收到消息	message
status-changed	状态变化	status
connecting	开始连接	-
reconnecting	开始重连	-
message-sent	消息已发送	message
message-queued	消息已加入队列	message
message-failed	消息发送失败	{ message, reason, error? }

Events 说明

connected

WebSocket 连接成功建立时触发。

disconnected

WebSocket 连接关闭时触发。参数包括：

• code: 关闭代码（数字）
• reason: 关闭原因（字符串）

error

发生错误时触发。参数为错误对象。

message

收到服务器消息时触发。参数为解析后的消息对象。

status-changed

连接状态变化时触发。参数为新的状态字符串，可能的值：

• disconnected: 未连接
• connecting: 连接中
• connected: 已连接
• reconnecting: 重连中
• error: 错误

connecting

开始建立连接时触发。

reconnecting

开始重连时触发。

message-sent

消息成功发送时触发。参数为发送的消息对象。

message-queued

消息加入队列时触发（连接未建立时）。参数为消息对象。

message-failed

消息发送失败时触发。参数为对象：

• message: 失败的消息对象
• reason: 失败原因（'queue_full' 或 'send_error'）
• error: 错误对象（仅在 reason 为 'send_error' 时存在）

Methods

组件通过 defineExpose 暴露了以下方法：

方法名	说明	参数	返回值
connect	连接 WebSocket	-	void
disconnect	断开连接	-	void
send	发送消息	(type, data)	void
reconnect	手动触发重连	-	void
getStatus	获取当前状态	-	string
isConnected	是否已连接	-	boolean
getQueueSize	获取队列长度	-	number

Methods 说明

connect

手动连接到 WebSocket 服务器。如果已经连接或正在连接，则跳过。

disconnect

断开 WebSocket 连接并停止所有定时器（心跳、重连等）。

send

发送消息到服务器。参数：

• type: 消息类型（字符串）
• data: 消息数据（对象）

如果连接已建立，消息会立即发送；否则加入队列。

reconnect

手动触发重连。通常不需要调用，组件会自动处理重连。

getStatus

返回当前连接状态字符串。

isConnected

返回布尔值，表示是否已连接。

getQueueSize

返回当前消息队列的长度。

消息协议

组件使用二进制协议发送和接收消息：

发送格式

字节 0: 消息类型（0=字符串，1=二进制）
字节 1-2: 扩展参数（2字节，小端序）
字节 3-6: 内容长度（4字节，小端序）
字节 7-N: 内容数据

发送的消息会被自动包装为以下格式：

{
  version: 1,  // 协议版本
  type: '...', // 消息类型
  data: {...}  // 消息数据
}

接收格式

组件会自动解析接收到的二进制消息，并触发 message 事件。解析后的消息格式与发送格式相同。

使用场景

场景 1：简单的实时通信

<script setup>
import CubeWebSocket from 'joyd.web.vue.cubelib'

const wsRef = ref(null)

const sendMessage = () => {
  wsRef.value?.send('chat', { text: 'Hello' })
}
</script>

<template>
  <CubeWebSocket
    ref="wsRef"
    ws-url="ws://localhost:8086/ws"
    @message="(msg) => console.log(msg)"
  />
  <button @click="sendMessage">发送消息</button>
</template>

场景 2：自动重连和错误处理

<script setup>
import { ref } from 'vue'
import CubeWebSocket from 'joyd.web.vue.cubelib'

const status = ref('disconnected')
const errorMessage = ref('')

const handleError = (error) => {
  errorMessage.value = error.message || '连接错误'
}
</script>

<template>
  <div>
    <div>状态: {{ status }}</div>
    <div v-if="errorMessage" class="error">{{ errorMessage }}</div>
    <CubeWebSocket
      ws-url="ws://localhost:8086/ws"
      :reconnect="true"
      @status-changed="status = $event"
      @error="handleError"
    />
  </div>
</template>

场景 3：消息队列监控

<script setup>
import { ref, watch } from 'vue'
import CubeWebSocket from 'joyd.web.vue.cubelib'

const wsRef = ref(null)
const queueSize = ref(0)

watch(queueSize, (newSize) => {
  if (newSize > 50) {
    console.warn('消息队列积压:', newSize)
  }
})
</script>

<template>
  <div>
    <div>队列大小: {{ queueSize }}</div>
    <CubeWebSocket
      ref="wsRef"
      ws-url="ws://localhost:8086/ws"
      @message-queued="queueSize++"
      @message-sent="queueSize--"
    />
  </div>
</template>

注意事项

1. URL 格式：确保 wsUrl 是有效的 WebSocket URL 格式（ws:// 或 wss:// 开头）
2. 调试模式：生产环境建议关闭 debugMode 以避免日志泄露
3. 消息队列：队列大小受 maxQueueSize 限制，超出部分会被丢弃
4. 心跳机制：心跳会定期发送 ping 消息，确保服务器端不会因超时断开连接
5. 重连策略：使用指数退避，避免频繁重连造成服务器压力
6. 组件清理：组件卸载时会自动断开连接并清理所有定时器

兼容性

• Chrome >= 16
• Firefox >= 11
• Safari >= 7
• Edge >= 12
• IE >= 10

许可证

MIT