useWebSocket

分类

导出大小

1.58 kB

上次更改

4 个月前

响应式 WebSocket 客户端。

用法

import { useWebSocket
 } from '@vueuse/core'

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

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

immediate

默认启用。

当调用此可组合函数时，立即建立连接。

autoConnect

默认启用。

如果 url 以 ref 的形式提供，当 url 改变时，它将自动重新连接到新的 url。

autoClose

默认启用。

当触发 beforeunload 事件或关联的效果作用域停止时，此功能将自动调用 close()。

autoReconnect

自动在错误时重新连接（默认禁用）。

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

或者对它的行为进行更多控制

const { status
, data
, close
 } = useWebSocket
('ws://websocketurl', {
  autoReconnect
: {
    retries
: 3,
    delay
: 1000,
    onFailed
() {
      alert
('Failed to connect WebSocket after 3 retries')
    },
  },
})

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

heartbeat

通常的做法是每隔一段时间发送一条小消息（心跳）以保持连接活跃。在此函数中，我们提供了一个方便的辅助函数来完成此操作

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。

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

类型声明

显示类型声明

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
  /**
   * Send heartbeat for every x milliseconds passed
   *
   * @default false
   */
  heartbeat
?:
    | boolean
    | {
        /**
         * Message for the heartbeat
         *
         * @default 'ping'
         */
        message
?: MaybeRefOrGetter
<WebSocketHeartbeatMessage
>
        /**
         * Response message for the heartbeat, if undefined the message will be used
         */
        responseMessage
?: MaybeRefOrGetter
<WebSocketHeartbeatMessage
>
        /**
         * Interval, in milliseconds
         *
         * @default 1000
         */
        interval
?: number
        /**
         * Heartbeat response timeout, in milliseconds
         *
         * @default 1000
         */
        pongTimeout
?: number
      }
  /**
   * Enabled auto reconnect
   *
   * @default false
   */
  autoReconnect
?:
    | boolean
    | {
        /**
         * Maximum retry times.
         *
         * Or you can pass a predicate function (which returns true if you want to retry).
         *
         * @default -1
         */
        retries
?: number | ((retried
: number) => boolean)
        /**
         * Delay for reconnect, in milliseconds
         *
         * @default 1000
         */
        delay
?: number
        /**
         * On maximum retry times reached.
         */
        onFailed
?: Fn

      }
  /**
   * Immediately open the connection when calling this composable
   *
   * @default true
   */
  immediate
?: boolean
  /**
   * Automatically connect to the websocket when URL changes
   *
   * @default true
   */
  autoConnect
?: boolean
  /**
   * Automatically close a connection
   *
   * @default true
   */
  autoClose
?: boolean
  /**
   * List of one or more sub-protocol strings
   *
   * @default []
   */
  protocols
?: string[]
}
export interface UseWebSocketReturn
<T
> {
  /**
   * Reference to the latest data received via the websocket,
   * can be watched to respond to incoming messages
   */
  data
: Ref
<T
 | null>
  /**
   * The current websocket status, can be only one of:
   * 'OPEN', 'CONNECTING', 'CLOSED'
   */
  status
: ShallowRef
<WebSocketStatus
>
  /**
   * Closes the websocket connection gracefully.
   */
  close
: WebSocket["close"]
  /**
   * Reopen the websocket connection.
   * If there the current one is active, will close it before opening a new one.
   */
  open
: Fn

  /**
   * Sends data through the websocket connection.
   *
   * @param data
   * @param useBuffer when the socket is not yet open, store the data into the buffer and sent them one connected. Default to true.
   */
  send
: (data
: string | ArrayBuffer | Blob, useBuffer
?: boolean) => boolean
  /**
   * Reference to the WebSocket instance.
   */
  ws
: Ref
<WebSocket | undefined>
}
/**
 * Reactive WebSocket client.
 *
 * @see https://vueuse.org.cn/useWebSocket
 * @param url
 */
export declare function useWebSocket
<Data
 = any>(
  url
: MaybeRefOrGetter
<string | URL | undefined>,
  options
?: UseWebSocketOptions,
): UseWebSocketReturn
<Data
>