useEventListener

用法

import { useEventListener } from '@vueuse/core'

useEventListener(document, 'visibilitychange', (evt) => {
  console.log(evt)
})

你也可以将一个 ref 作为事件目标传递给 useEventListener 当你改变目标时，useEventListener 会注销之前的事件并注册新的事件。

TypeScript

import { useEventListener } from '@vueuse/core'

const element = ref<HTMLDivElement>()
useEventListener(element, 'keydown', (e) => {
  console.log(e.key)
})

import { useEventListener } from '@vueuse/core'
const element = ref()
useEventListener(element, 'keydown', (e) => {
  console.log(e.key)
})

vue

<template>
  <div v-if="cond" ref="element">
    Div1
  </div>
  <div v-else ref="element">
    Div2
  </div>
</template>

你也可以调用返回的函数来注销监听器。

import { useEventListener } from '@vueuse/core'

const cleanup = useEventListener(document, 'keydown', (e) => {
  console.log(e.key)
})

cleanup() // 这将注销监听器。

注意，如果你的组件也在 SSR（服务器端渲染）中运行，你可能会遇到错误（如 document is not defined），因为类似 document 和 window 的 DOM API 在 Node.js 中不可用。为了避免这种情况，你可以将逻辑放在 onMounted 钩子内部。

// onMounted 只会在客户端执行，所以它保证了 DOM API 是可用的。
onMounted(() => {
  useEventListener(document, 'keydown', (e) => {
    console.log(e.key)
  })
})

类型声明

显示类型声明

typescript

interface InferEventTarget<Events> {
  addEventListener: (event: Events, fn?: any, options?: any) => any
  removeEventListener: (event: Events, fn?: any, options?: any) => any
}
export type WindowEventName = keyof WindowEventMap
export type DocumentEventName = keyof DocumentEventMap
export interface GeneralEventListener<E = Event> {
  (evt: E): void
}
/**
 * 在挂载时使用 addEventListener 进行注册，并在卸载时自动使用 removeEventListener 进行移除。
 *
 * 重载 1：监听 window 事件
 *
 * @see https://vueuse.org/useEventListener
 * @param event 事件类型或事件类型数组。
 * @param listener 事件监听器或事件监听器数组。
 * @param options 可选项，用于配置事件监听的行为。
 */
export declare function useEventListener<E extends keyof WindowEventMap>(
  event: Arrayable<E>,
  listener: Arrayable<(this: Window, ev: WindowEventMap[E]) => any>,
  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
 * 在挂载时使用 addEventListener 进行注册，并在卸载时自动使用 removeEventListener 进行移除。
 *
 * 重载 2：显式指定了 Window 目标
 *
 * @see https://vueuse.org/useEventListener
 * @param target Window 目标对象。
 * @param event 事件类型或事件类型数组。
 * @param listener 事件监听器或事件监听器数组。
 * @param options 可选项，用于配置事件监听的行为。
 */
export declare function useEventListener<E extends keyof WindowEventMap>(
  target: Window,
  event: Arrayable<E>,
  listener: Arrayable<(this: Window, ev: WindowEventMap[E]) => any>,
  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
 * 在挂载时使用 addEventListener 进行注册，并在卸载时自动使用 removeEventListener 进行移除。
 *
 * 重载 3：显式指定了 Document 目标
 *
 * @see https://vueuse.org/useEventListener
 * @param target Document 或 ShadowRoot 目标对象。
 * @param event 事件类型或事件类型数组。
 * @param listener 事件监听器或事件监听器数组。
 * @param options 可选项，用于配置事件监听的行为。
 */
export declare function useEventListener<E extends keyof DocumentEventMap>(
  target: DocumentOrShadowRoot,
  event: Arrayable<E>,
  listener: Arrayable<(this: Document, ev: DocumentEventMap[E]) => any>,
  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
 * 在挂载时使用 addEventListener 进行注册，并在卸载时自动使用 removeEventListener 进行移除。
 *
 * 重载 4：显式指定了 HTMLElement 目标
 *
 * @see https://vueuse.org/useEventListener
 * @param target HTMLElement 目标对象。
 * @param event 事件类型或事件类型数组。
 * @param listener 事件监听器。
 * @param options 可选项，用于配置事件监听的行为。
 */
export declare function useEventListener<E extends keyof HTMLElementEventMap>(
  target: MaybeRefOrGetter<HTMLElement | null | undefined>,
  event: Arrayable<E>,
  listener: (this: HTMLElement, ev: HTMLElementEventMap[E]) => any,
  options?: boolean | AddEventListenerOptions,
): () => void
/**
 * 在挂载时使用 addEventListener 进行注册，并在卸载时自动使用 removeEventListener 进行移除。
 *
 * 重载 5：自定义事件目标，并推断事件类型
 *
 * @see https://vueuse.org/useEventListener
 * @param target 自定义事件目标对象，根据事件名推断。
 * @param event 事件类型或事件类型数组。
 * @param listener 事件监听器或事件监听器数组。
 * @param options 可选项，用于配置事件监听的行为。
 */
export declare function useEventListener<
  Names extends string,
  EventType = Event,
>(
  target: MaybeRefOrGetter<InferEventTarget<Names> | null | undefined>,
  event: Arrayable<Names>,
  listener: Arrayable<GeneralEventListener<EventType>>,
  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
 * 在挂载时使用 addEventListener 进行注册，并在卸载时自动使用 removeEventListener 进行移除。
 *
 * 重载 6：自定义事件目标，通用型
 *
 * @see https://vueuse.org/useEventListener
 * @param target 自定义事件目标对象。
 * @param event 事件类型或事件类型数组。
 * @param listener 事件监听器或事件监听器数组。
 * @param options 可选项，用于配置事件监听的行为。
 */
export declare function useEventListener<EventType = Event>(
  target: MaybeRefOrGetter<EventTarget | null | undefined>,
  event: Arrayable<string>,
  listener: Arrayable<GeneralEventListener<EventType>>,
  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn