useEventSource

类别

导出体积

679 B

上次更改

2 minutes ago

一个 EventSource 或 Server-Sent-Events 实例打开了与 HTTP 服务器的持久连接，服务器以 text/event-stream 格式发送事件。

用法

import { useEventSource } from '@vueuse/core'

const { status, data, error, close } = useEventSource('https://event-source-url')

查看类型声明以获取更多选项。

命名事件

你可以使用第二个参数定义命名事件

TypeScript

import { useEventSource } from '@vueuse/core'

const { event, data } = useEventSource('https://event-source-url', ['notice', 'update'] as const)

import { useEventSource } from '@vueuse/core'
const { event, data } = useEventSource('https://event-source-url', [
  'notice',
  'update',
])

立即连接

自动连接 (默认启用)。

这将自动为你调用 open()，你无需自行调用它。

如果 URL 作为一个 ref 提供，这也控制了在其值更改时是否重新建立连接 (或者是否需要再次调用 open() 才能生效)。

自动重连

自动在发生错误时重新连接 (默认禁用)。

const { status, data, close } = useEventSource('https://event-source-url', [], {
  autoReconnect: true,
})

或者使用更多对其行为的控制：

const { status, data, close } = useEventSource('https://event-source-url', [], {
  autoReconnect: {
    retries: 3,
    delay: 1000,
    onFailed() {
      alert('重试 3 次后无法连接 EventSource')
    },
  },
})

类型声明

显示类型声明

typescript

export type EventSourceStatus = "CONNECTING" | "OPEN" | "CLOSED"
export interface UseEventSourceOptions extends EventSourceInit {
  /**
   * 启用自动重连
   *
   * @default false
   */
  autoReconnect?:
    | boolean
    | {
        /**
         * 最大重试次数。
         *
         * 或者你可以传递一个断言函数（如果要重试，则返回true）。
         *
         * @default -1
         */
        retries?: number | (() => boolean)
        /**
         * 重连延迟，单位为毫秒
         *
         * @default 1000
         */
        delay?: number
        /**
         * 在达到最大重试次数时触发。
         */
        onFailed?: Fn
      }
  /**
   * 自动打开连接
   *
   * @default true
   */
  immediate?: boolean
}
export interface UseEventSourceReturn<Events extends string[]> {
  /**
   * 对通过 EventSource 接收到的最新数据的 ref，
   * 可以被监视以响应传入的消息
   */
  data: Ref<string | null>
  /**
   * 连接的当前状态，只能是以下之一：
   * 'CONNECTING', 'OPEN', 'CLOSED'
   */
  status: Ref<EventSourceStatus>
  /**
   * 最新的命名事件
   */
  event: Ref<Events[number] | null>
  /**
   * 当前错误
   */
  error: Ref<Event | null>
  /**
   * 优雅地关闭 EventSource 连接。
   */
  close: EventSource["close"]
  /**
   * 重新打开 EventSource 连接。
   * 如果当前连接处于活动状态，则会在打开新连接之前关闭当前连接。
   */
  open: Fn
  /**
   * 对当前 EventSource 实例的 ref。
   */
  eventSource: Ref<EventSource | null>
  /**
   * The last event ID string, for server-sent events.
   * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/lastEventId
   */
  lastEventId: Ref<string | null>
}
/**
 * EventSource 的响应式包装器。
 *
 * @see https://vueuse.org/useEventSource
 * @see https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource EventSource
 * @param url
 * @param events
 * @param options
 */
export declare function useEventSource<Events extends string[]>(
  url: MaybeRefOrGetter<string | URL | undefined>,
  events?: Events,
  options?: UseEventSourceOptions,
): UseEventSourceReturn<Events>