useWebSocket

カテゴリー

エクスポートサイズ

1.34 kB

最終更新日

先週

リアクティブな WebSocket クライアント。

使い方

import { useWebSocket } from '@vueuse/core'

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

詳細なオプションについては、型宣言を参照してください。

即時性

自動接続（デフォルトで有効）。

これにより、open() が自動的に呼び出され、自分で呼び出す必要はありません。

url が ref として提供される場合、その値が変更されたときに接続を再確立するかどうか（または、変更を有効にするために open() を再度呼び出す必要があるかどうか）も制御します。

自動クローズ

自動接続クローズ（デフォルトで有効）。

これにより、beforeunload イベントがトリガーされたとき、または関連付けられた効果スコープが停止したときに、自動的に close() が呼び出されます。

自動再接続

エラー時に自動的に再接続します（デフォルトでは無効）。

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() を呼び出しても、自動再接続はトリガーされません。

ハートビート

接続をアクティブに保つために、一定時間が経過するごとに小さなメッセージ（ハートビート）を送信するのが一般的な方法です。この関数では、それを実行するための便利なヘルパーを提供します。

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

または、より詳細な制御

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

サブプロトコル

使用する1つ以上のサブプロトコルのリスト。この場合は 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
  /**
   * Send heartbeat for every x milliseconds passed
   *
   * @default false
   */
  heartbeat?:
    | boolean
    | {
        /**
         * Message for the heartbeat
         *
         * @default 'ping'
         */
        message?: string | ArrayBuffer | Blob
        /**
         * Response message for the heartbeat, if undefined the message will be used
         */
        responseMessage?: string | ArrayBuffer | Blob
        /**
         * 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 | (() => boolean)
        /**
         * Delay for reconnect, in milliseconds
         *
         * @default 1000
         */
        delay?: number
        /**
         * On maximum retry times reached.
         */
        onFailed?: Fn
      }
  /**
   * Automatically open a connection
   *
   * @default true
   */
  immediate?: 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: Ref<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.dokyumento.jp/useWebSocket
 * @param url
 */
export declare function useWebSocket<Data = any>(
  url: MaybeRefOrGetter<string | URL | undefined>,
  options?: UseWebSocketOptions,
): UseWebSocketReturn<Data>