useEventSource

分类

导出大小

1.12 kB

上次更改

2 个月前

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

用法

import { useEventSource
 } from '@vueuse/core'

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

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

命名事件

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

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

immediate

默认启用。

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

autoConnect

默认启用。

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

错误时自动重连

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

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
('Failed to connect EventSource after 3 retries')
      },
    },
  }
)

数据序列化

使用序列化函数对传入数据应用自定义转换。

const { data
 } = useEventSource
(
  'https://event-source-url',
  [],
  {
    serializer
: {
      read
: rawData
 => JSON
.parse
(rawData
),
    },
  }
)

// If server sends: '{"name":"John","age":30}'
// data.value will be: { name: 'John', age: 30 }

类型声明

显示类型声明

export type EventSourceStatus
 = "CONNECTING" | "OPEN" | "CLOSED"
export interface UseEventSourceOptions
<Data
> extends EventSourceInit {
  /**
   * 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

      }
  /**
   * Immediately open the connection when calling this composable
   *
   * @default true
   */
  immediate
?: boolean
  /**
   * Automatically connect to the websocket when URL changes
   *
   * @default true
   */
  autoConnect
?: boolean
  /**
   * Custom data serialization
   */
  serializer
?: {
    read
: (v
?: string) => Data

  }
}
export interface UseEventSourceReturn
<Events
 extends string[], Data
 = any> {
  /**
   * Reference to the latest data received via the EventSource,
   * can be watched to respond to incoming messages
   */
  data
: ShallowRef
<Data
 | null>
  /**
   * The current state of the connection, can be only one of:
   * 'CONNECTING', 'OPEN' 'CLOSED'
   */
  status
: ShallowRef
<EventSourceStatus
>
  /**
   * The latest named event
   */
  event
: ShallowRef
<Events
[number] | null>
  /**
   * The current error
   */
  error
: ShallowRef
<Event | null>
  /**
   * Closes the EventSource connection gracefully.
   */
  close
: EventSource["close"]
  /**
   * Reopen the EventSource connection.
   * If there the current one is active, will close it before opening a new one.
   */
  open
: Fn

  /**
   * Reference to the current EventSource instance.
   */
  eventSource
: Ref
<EventSource | null>
  /**
   * The last event ID string, for server-sent events.
   * @see https://mdn.org.cn/en-US/docs/Web/API/MessageEvent/lastEventId
   */
  lastEventId
: ShallowRef
<string | null>
}
/**
 * Reactive wrapper for EventSource.
 *
 * @see https://vueuse.org.cn/useEventSource
 * @see https://mdn.org.cn/en-US/docs/Web/API/EventSource/EventSource EventSource
 * @param url
 * @param events
 * @param options
 */
export declare function useEventSource
<Events
 extends string[], Data
 = any>(
  url
: MaybeRefOrGetter
<string | URL | undefined>,
  events
?: Events
,
  options
?: UseEventSourceOptions
<Data
>,
): UseEventSourceReturn
<Events
, Data
>