useEventListener
轻松使用 EventListener。在挂载时使用 addEventListener 注册，在卸载时自动使用 removeEventListener。
用法
ts
import { useEventListener } from '@vueuse/core'
useEventListener(document, 'visibilitychange', (evt) => {
console.log(evt)
})你也可以将一个 ref 作为事件目标传递，当你更改目标时，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>你也可以调用返回的函数来注销监听器。
ts
import { useEventListener } from '@vueuse/core'
const cleanup = useEventListener(document, 'keydown', (e) => {
console.log(e.key)
})
cleanup() // This will unregister the listener.请注意，如果你的组件也在 SSR（服务器端渲染）中运行，你可能会收到错误（例如 document is not defined），因为像 document 和 window 这样的 DOM API 在 Node.js 中不可用。为了避免这种情况，你可以将逻辑放在 onMounted 钩子中。
ts
// 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)
})
})类型声明
显示类型声明
ts
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.cn/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.cn/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.cn/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.cn/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.cn/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.cn/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.cn/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来源
贡献者
Anthony Fu
Anthony Fu
IlyaL
丶远方
SerKo
Arthur Darkstone
Fernando Fernández
我想静静
Forrest Li
陪我去看海吧
Julien Le Coupanec
Michael J. Roberts
James Garbutt
vaakian X
sun0day
Alejandro Arevalo
Jelf
Alex Kozack
lstoeferle
Antério Vieira