useEventListener

类别

导出体积

588 B

上次更改

2 months ago

轻松使用 EventListener。在组件挂载时使用 addEventListener 进行注册，在组件卸载时自动使用 removeEventListener 进行注销。

用法

import { useEventListener
 } from '@vueuse/core'

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

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

vue

<script setup lang="ts">
import { useEventListener
 } from '@vueuse/core'
import { useTemplateRef
 } from 'vue'

const element
 = useTemplateRef
('element')
useEventListener
(element
, 'keydown', (e
) => {
  console
.log
(e
.key
)
})
</script>

<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 will only be called in the client side
// so it guarantees the DOM APIs are available.
onMounted
(() => {
  useEventListener
(document
, 'keydown', (e
) => {
    console
.log
(e
.key
)
  })
})

类型声明

显示类型声明

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 type ShadowRootEventName
 = keyof ShadowRootEventMap
export interface GeneralEventListener
<E
 = Event> {
  (evt
: E
): void
}
/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 1: Omitted Window target
 *
 * @see https://vueuse.org/useEventListener
 */
export declare function useEventListener
<E
 extends keyof WindowEventMap>(
  event
: MaybeRefOrGetter
<Arrayable
<E
>>,
  listener
: MaybeRef
<Arrayable
<(this
: Window, ev
: WindowEventMap[E
]) => any>>,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn

/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 2: Explicitly Window target
 *
 * @see https://vueuse.org/useEventListener
 * @param target
 * @param event
 * @param listener
 * @param options
 */
export declare function useEventListener
<E
 extends keyof WindowEventMap>(
  target
: Window,
  event
: MaybeRefOrGetter
<Arrayable
<E
>>,
  listener
: MaybeRef
<Arrayable
<(this
: Window, ev
: WindowEventMap[E
]) => any>>,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn

/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 3: Explicitly Document target
 *
 * @see https://vueuse.org/useEventListener
 */
export declare function useEventListener
<E
 extends keyof DocumentEventMap>(
  target
: Document,
  event
: MaybeRefOrGetter
<Arrayable
<E
>>,
  listener
: MaybeRef
<
    Arrayable
<(this
: Document, ev
: DocumentEventMap[E
]) => any>
  >,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn

/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 4: Explicitly ShadowRoot target
 *
 * @see https://vueuse.org/useEventListener
 */
export declare function useEventListener
<E
 extends keyof ShadowRootEventMap>(
  target
: MaybeRefOrGetter
<Arrayable
<ShadowRoot> | null | undefined>,
  event
: MaybeRefOrGetter
<Arrayable
<E
>>,
  listener
: MaybeRef
<
    Arrayable
<(this
: ShadowRoot, ev
: ShadowRootEventMap[E
]) => any>
  >,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn

/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 5: Explicitly HTMLElement target
 *
 * @see https://vueuse.org/useEventListener
 */
export declare function useEventListener
<E
 extends keyof HTMLElementEventMap>(
  target
: MaybeRefOrGetter
<Arrayable
<HTMLElement> | null | undefined>,
  event
: MaybeRefOrGetter
<Arrayable
<E
>>,
  listener
: MaybeRef
<(this
: HTMLElement, ev
: HTMLElementEventMap[E
]) => any>,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn

/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 6: Custom event target with event type infer
 *
 * @see https://vueuse.org/useEventListener
 */
export declare function useEventListener
<
  Names
 extends string,
  EventType
 = Event,
>(
  target
: MaybeRefOrGetter
<
    Arrayable
<InferEventTarget
<Names
>> | null | undefined
  >,
  event
: MaybeRefOrGetter
<Arrayable
<Names
>>,
  listener
: MaybeRef
<Arrayable
<GeneralEventListener
<EventType
>>>,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn

/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 7: Custom event target fallback
 *
 * @see https://vueuse.org/useEventListener
 */
export declare function useEventListener
<EventType
 = Event>(
  target
: MaybeRefOrGetter
<Arrayable
<EventTarget> | null | undefined>,
  event
: MaybeRefOrGetter
<Arrayable
<string>>,
  listener
: MaybeRef
<Arrayable
<GeneralEventListener
<EventType
>>>,
  options
?: MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
): Fn