useWebSocket

类别

导出体积

1.57 kB

上次更改

yesterday

响应式的 WebSocket 客户端。

用法

import { useWebSocket
 } from '@vueuse/core'

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

Return Values

Property	Type	Description
`data`	`Ref<any>`	Latest received data
`status`	`Ref<'OPEN' \| 'CONNECTING' \| 'CLOSED'>`	Connection status
`ws`	`Ref<WebSocket>`	WebSocket instance
`send`	`(data, useBuffer?) => boolean`	Send data (buffers if not connected)
`open`	`() => void`	Open/reconnect the connection
`close`	`(code?, reason?) => void`	Close the connection

Callbacks

const { data
 } = useWebSocket('ws://websocketurl', {
  onConnected
(ws
) {
    console
.log
('Connected!')
  },
  onDisconnected
(ws
, event
) {
    console
.log
('Disconnected!', event
.code)
  },
  onError
(ws
, event
) {
    console
.error
('Error:', event
)
  },
  onMessage
(ws
, event
) {
    console
.log
('Message:', event
.data)
  },
})

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

immediate

默认启用。

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

autoConnect

默认启用。

如果 URL 作为 ref 提供，当 URL 发生变化时，它将自动重新连接到新 URL。

autoClose

默认启用。

当触发 beforeunload 事件或关联的 effect 范围停止时，这将自动调用 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
('重试 3 次后无法连接 WebSocket')
    },
  },
})

你也可以传入一个函数给 delay，根据重试次数计算延迟时间。这在实现指数退避时非常有用：

const { status
, data
, close
 } = useWebSocket
('ws://websocketurl', {
  autoReconnect
: {
    retries
: 5,
    // 指数退避：1秒，2秒，4秒，8秒，16秒
    delay
: retries
 => Math
.min
(1000 * 2 ** (retries
 - 1), 30000),
  },
})

const { status
, data
, close
 } = useWebSocket
('ws://websocketurl', {
  autoReconnect
: {
    retries
: 5,
    // 线性退避：1秒，2秒，3秒，4秒，5秒
    delay
: retries
 => retries
 * 1000,
  },
})

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

heartbeat

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

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

或者具有更多控制：

const { status
, data
, close
 } = useWebSocket
('ws://websocketurl', {
  heartbeat
: {
    message
: 'ping',
    scheduler
: cb
 => useIntervalFn(cb
, 2000),
    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
  /**
   * 每过 x 毫秒发送一次心跳。
   *
   * @default false
   */
  heartbeat
?:
    | boolean
    | (ConfigurableScheduler
 & {
        /**
         * 心跳消息
         *
         * @default 'ping'
         */
        message
?: MaybeRefOrGetter
<WebSocketHeartbeatMessage
>
        /**
         * 心跳的响应消息，如果未定义，将使用该消息
         */
        responseMessage
?: MaybeRefOrGetter
<WebSocketHeartbeatMessage
>
        /**
         * 间隔时间，毫秒为单位
         *
         * @deprecated Please use `scheduler` option instead
         * @default 1000
         */
        interval
?: number
        /**
         * 心跳响应超时时间，毫秒为单位
         *
         * @default 1000
         */
        pongTimeout
?: number
      })
  /**
   * 启用自动重新连接
   *
   * @default false
   */
  autoReconnect
?:
    | boolean
    | {
        /**
         * 最大重试次数。
         *
         * 或者你可以传递一个谓词函数（如果要重试，则返回 true）。
         *
         * @default -1
         */
        retries
?: number | ((retried
: number) => boolean)
        /**
         * 重新连接延迟，毫秒为单位
         *
         * Or you can pass a function to calculate the delay based on the number of retries.
         *
         * @default 1000
         */
        delay
?: number | ((retries
: number) => 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
: ShallowRef
<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
: ShallowRef
<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
>