实时通信 Hooks：useWebSocket

useWebSocket 是组件库的业务级 WebSocket hooks：断线自动重连（指数退避 + 次数上限）、心跳保活、收发自动 JSON 编解码、按消息 type 分发、页面隐藏暂停（可选）、作用域销毁自动断开。通知中心实时推送、大屏实时刷新、协同状态同步场景开箱即用。

基础用法

vue

<script setup lang="ts">
import { useWebSocket } from 'vue3-ep-biz-lib'

const ws = useWebSocket({
  url: () => `wss://example.com/ws?token=${token.value}`,
  onMessage: (data) => console.log('收到', data),
})

// 发送（对象自动 JSON 序列化）
ws.send({ type: 'subscribe', channel: 'order-notice' })
</script>

<template>
  <span>{{ ws.status.value }}</span>
</template>

按消息 type 分发

约定消息体为 { type, payload } 时，on(type, handler) 精确订阅，返回退订函数：

const ws = useWebSocket({ url: 'wss://example.com/ws' })

const off = ws.on('notice', (payload) => renderNotice(payload))
const offOrder = ws.on('order-change', (payload) => refreshOrder(payload))

onUnmounted(() => {
  off()
  offOrder()
})

自动重连与心跳

const ws = useWebSocket({
  url: 'wss://example.com/ws',
  heartbeat: { interval: 15000, message: 'ping' },
  reconnect: { enable: true, retries: 5, delay: 1000, maxDelay: 30000 },
  onReconnect: (attempt, delay) => console.log(`第 ${attempt} 次重连，${delay}ms 后`),
  onFail: () => console.warn('重连耗尽，请检查网络'),
})

重连延迟按 delay × 2^n 指数退避、封顶 maxDelay；连上后 attempt 归零。手动 close() 后不再自动重连。

页面隐藏暂停

pauseOnHidden: true：切后台断开省流量 / 省连接，回到前台自动按当前 url 重连——大屏与看板场景常用。

API

useWebSocket(options): `UseWebSocketReturn`

成员	类型	说明
status	`Ref<'connecting' \| 'open' \| 'closing' \| 'closed'>`	连接状态
data	`Ref<unknown>`	最近一条消息载荷（autoJson 时已解析）
attempt	`Ref<number>`	已重连次数（连上后归零）
send	`(data) => boolean`	发送（autoJson 自动序列化）；未连接返回 false
open	`() => void`	手动连接（immediate: false 时使用）
close	`(code?, reason?) => void`	手动关闭，不再自动重连
on	`(type, handler) => () => void`	按 `message.type` 订阅，返回退订函数

options

属性	类型	默认值	说明
url	`string \| (() => string)`	—（必填）	连接地址；函数形式变化时自动重连
protocols	`string \| string[]`	—	子协议
immediate	`boolean`	`true`	挂载后立即连接
heartbeat	`{ interval?; message? }`	不开启	心跳间隔毫秒与报文
reconnect	`{ enable?; retries?; delay?; maxDelay? }`	开启 / Infinity / 1000 / 30000	自动重连（指数退避）
autoJson	`boolean`	`true`	收发自动 JSON 编解码
pauseOnHidden	`boolean`	`false`	页面隐藏断开、可见恢复
onOpen / onClose / onError	`(event) => void`	—	连接事件
onMessage	`(data, raw) => void`	—	收到消息（data 已解析）
onReconnect	`(attempt, delay) => void`	—	准备发起第 attempt 次重连
onFail	`() => void`	—	重试耗尽

实时通信 Hooks：useWebSocket ​

基础用法 ​

按消息 type 分发 ​

自动重连与心跳 ​

页面隐藏暂停 ​

API ​

useWebSocket(options): UseWebSocketReturn ​

options ​