useWebSocket
响应式 WebSocket 客户端。
用法
ts
import { useWebSocket } from '@vueuse/core'
const { status, data, send, open, close } = useWebSocket('ws://websocketurl')有关更多选项，请参阅类型声明。
immediate
默认启用。
在调用此组合时立即建立连接。
autoConnect
默认启用。
如果 URL 作为 ref 提供，当 URL 发生变化时，它将自动重新连接到新 URL。
autoClose
默认启用。
当触发 beforeunload 事件或关联的 effect 范围停止时，这将自动调用 close()。
autoReconnect
在错误发生时自动重连 (默认禁用)。
ts
const { status, data, close } = useWebSocket('ws://websocketurl', {
autoReconnect: true,
})或者具有更多控制其行为的选项：
ts
const { status, data, close } = useWebSocket('ws://websocketurl', {
autoReconnect: {
retries: 3,
delay: 1000,
onFailed() {
alert('重试 3 次后无法连接 WebSocket')
},
},
})显式调用 close() 不会触发自动重新连接。
heartbeat
通常会在每隔一段时间发送一个小消息 (心跳) 以保持连接活动状态。在此函数中，我们提供了一个便利的辅助工具来执行此操作：
ts
const { status, data, close } = useWebSocket('ws://websocketurl', {
heartbeat: true,
})或者具有更多控制：
ts
const { status, data, close } = useWebSocket('ws://websocketurl', {
heartbeat: {
message: 'ping',
interval: 1000,
pongTimeout: 1000,
},
})子协议
要使用的一个或多个子协议列表，在这种情况下是 soap 和 wamp。
ts
const { status, data, send, open, close } = useWebSocket('ws://websocketurl', {
protocols: ['soap'], // ['soap', 'wamp']
})类型声明
显示类型声明
ts
export type WebSocketStatus = "OPEN" | "CONNECTING" | "CLOSED"
export type WebSocketHeartbeatMessage = string | ArrayBuffer | Blob
export interface UseWebSocketOptions {
onConnected?: (ws: WebSocket) => void
onDisconnected?: (ws: WebSocket, event: CloseEvent) => void
onError?: (ws: WebSocket, event: Event) => void
onMessage?: (ws: WebSocket, event: MessageEvent) => void
/**
* 每过 x 毫秒发送一次心跳。
*
* @default false
*/
heartbeat?:
| boolean
| {
/**
* 心跳消息
*
* @default 'ping'
*/
message?: MaybeRefOrGetter<WebSocketHeartbeatMessage>
/**
* 心跳的响应消息，如果未定义，将使用该消息
*/
responseMessage?: MaybeRefOrGetter<WebSocketHeartbeatMessage>
/**
* 间隔时间，毫秒为单位
*
* @default 1000
*/
interval?: number
/**
* 心跳响应超时时间，毫秒为单位
*
* @default 1000
*/
pongTimeout?: number
}
/**
* 启用自动重新连接
*
* @default false
*/
autoReconnect?:
| boolean
| {
/**
* 最大重试次数。
*
* 或者你可以传递一个谓词函数（如果要重试，则返回 true）。
*
* @default -1
*/
retries?: number | ((retried: number) => boolean)
/**
* 重新连接延迟，毫秒为单位
*
* @default 1000
*/
delay?: number
/**
* 当达到最大重试次数时。
*/
onFailed?: Fn
}
/**
* Immediately open the connection when calling this composable
*
* @default true
*/
immediate?: boolean
/**
* 当 URL 发生变化时自动连接到 WebSocket
*
* @default true
*/
autoConnect?: boolean
/**
* 自动关闭连接
*
* @default true
*/
autoClose?: boolean
/**
* 一个或多个子协议字符串的列表
*
* @default []
*/
protocols?: string[]
}
export interface UseWebSocketReturn<T> {
/**
* WebSocket 最新接收到的数据的 ref，可以监听以响应传入的消息
*/
data: Ref<T | null>
/**
* 当前 WebSocket 的状态，只能是以下之一：
* 'OPEN'，'CONNECTING'，'CLOSED'
*/
status: ShallowRef<WebSocketStatus>
/**
* 优雅地关闭 WebSocket 连接。
*/
close: WebSocket["close"]
/**
* 重新打开 WebSocket 连接。
* 如果当前连接处于活动状态，将在打开新连接之前关闭它。
*/
open: Fn
/**
* 通过 WebSocket 连接发送数据。
*
* @param data
* @param useBuffer 当套接字尚未打开时，将数据存储到缓冲区并在连接时发送。默认为 true。
*/
send: (data: string | ArrayBuffer | Blob, useBuffer?: boolean) => boolean
/**
* WebSocket 实例的 ref。
*/
ws: Ref<WebSocket | undefined>
}
/**
* 响应式 WebSocket 客户端。
*
* @see https://vueuse.org/useWebSocket
* @param url
*/
export declare function useWebSocket<Data = any>(
url: MaybeRefOrGetter<string | URL | undefined>,
options?: UseWebSocketOptions,
): UseWebSocketReturn<Data>源码
贡献者
一纸忘忧