useEventListener

类别

Browser

导出大小

532 B

最近修改

2 days ago

轻松使用 EventListener。在挂载时使用 addEventListener 注册，在卸载时自动使用 removeEventListener。

🌐 Use EventListener with ease. Register using addEventListener on mounted, and removeEventListener automatically on unmounted.

用法

🌐 Usage

import { useEventListener } from '@vueuse/core'

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

默认目标

🌐 Default Target

当省略目标时，默认值为 window：

🌐 When the target is omitted, it defaults to window:

import { useEventListener } from '@vueuse/core'

// Listens on window
useEventListener('resize', (evt) => {
  console.log(evt)
})

反应靶

🌐 Reactive Target

你可以将 ref 作为事件目标，当目标变化时，useEventListener 会注销之前的事件并注册新的事件。

🌐 You can pass a ref as the event target, useEventListener will unregister the previous event and register the new one when the target changes.

<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>

多个事件

🌐 Multiple Events

你可以传递一个事件数组来同时监听多个事件：

🌐 You can pass an array of events to listen to multiple events at once:

import { useEventListener } from '@vueuse/core'

useEventListener(document, ['mouseenter', 'mouseleave'], (evt) => {
  console.log(evt.type)
})

多个目标

🌐 Multiple Targets

你也可以传递一个目标数组：

🌐 You can also pass an array of targets:

import { useEventListener } from '@vueuse/core'

const buttons = document.querySelectorAll('button')
useEventListener(buttons, 'click', (evt) => {
  console.log('Button clicked')
})

清理

🌐 Cleanup

返回一个清理函数以手动注销监听器：

🌐 Returns a cleanup function to manually unregister the listener:

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 钩子中。

🌐 Note if your components also run in SSR (Server Side Rendering), you might get errors (like document is not defined) because DOM APIs like document and window are not available in Node.js. To avoid that you can put the logic inside onMounted hook.

// 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)
  })
})