useWebSocket

用法

import { useWebSocket } from '@vueuse/core'

const { status, data, send, open, close } = useWebSocket('ws://websocketurl')

有关更多选项，请参阅类型声明。

立即连接

自动连接（默认启用）。

这将自动为您调用 open()，您不需要自己调用它。

如果 URL 作为 ref 提供，则它还控制在其值更改时是否重新建立连接（或者您需要再次调用 open() 以使更改生效）。

自动关闭连接

自动关闭连接（默认启用）。

当触发 beforeunload 事件或关联的 effect 范围停止时，这将自动调用 close()。

自动重连

在错误发生时自动重连（默认禁用）。

const { status, data, close } = useWebSocket('ws://websocketurl', {
  autoReconnect: true,
})

或者具有更多控制其行为的选项：

const { status, data, close } = useWebSocket('ws://websocketurl', {
  autoReconnect: {
    retries: 3,
    delay: 1000,
    onFailed() {
      alert('重试 3 次后无法连接 WebSocket')
    },
  },
})

显式调用 close() 不会触发自动重新连接。

心跳

通常会在每隔一段时间发送一个小消息（心跳）以保持连接活动状态。在此函数中，我们提供了一个便利的辅助工具来执行此操作：

const { status, data, close } = useWebSocket('ws://websocketurl', {
  heartbeat: true,
})

或者具有更多控制：

const { status, data, close } = useWebSocket('ws://websocketurl', {
  heartbeat: {
    message: 'ping',
    interval: 1000,
    pongTimeout: 1000,
  },
})

子协议

要使用的一个或多个子协议列表，在这种情况下是 soap 和 wamp。

import { useWebSocket } from '@vueuse/core'

const { status, data, send, open, close } = useWebSocket('ws://websocketurl', {
  protocols: ['soap'], // ['soap', 'wamp']
})

类型声明

显示类型声明

typescript

export type WebSocketStatus = "OPEN" | "CONNECTING" | "CLOSED"
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?: string | ArrayBuffer | Blob
        /**
         * Response message for the heartbeat, if undefined the message will be used
         */
        responseMessage?: string | ArrayBuffer | Blob
        /**
         * 间隔时间，毫秒为单位
         *
         * @default 1000
         */
        interval?: number
        /**
         * 心跳响应超时时间，毫秒为单位
         *
         * @default 1000
         */
        pongTimeout?: number
      }
  /**
   * 启用自动重新连接
   *
   * @default false
   */
  autoReconnect?:
    | boolean
    | {
        /**
         * 最大重试次数。
         *
         * 或者您可以传递一个谓词函数（如果要重试，则返回 true）。
         *
         * @default -1
         */
        retries?: number | (() => boolean)
        /**
         * 重新连接延迟，毫秒为单位
         *
         * @default 1000
         */
        delay?: number
        /**
         * 当达到最大重试次数时。
         */
        onFailed?: Fn
      }
  /**
   * 自动打开连接
   *
   * @default true
   */
  immediate?: boolean
  /**
   * 自动关闭连接
   *
   * @default true
   */
  autoClose?: boolean
  /**
   * 一个或多个子协议字符串的列表
   *
   * @default []
   */
  protocols?: string[]
}
export interface UseWebSocketReturn<T> {
  /**
   * WebSocket 最新接收到的数据的 ref，可以监听以响应传入的消息
   */
  data: Ref<T | null>
  /**
   * 当前 WebSocket 的状态，只能是以下之一：
   * 'OPEN'，'CONNECTING'，'CLOSED'
   */
  status: Ref<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>