在 Vue 中动态移除事件监听器的正确姿势

这是一份关于在 Vue 中尝试通过 removeEventListener 移除事件监听器但失败的案例分析，以及对应的解决方案。

核心问题

在 Vue 组件中，通过模板引用 (ref) 获取到 DOM 元素，并使用 @mousemove 指令绑定了一个事件。现在希望通过一个按钮点击事件来调用 removeEventListener 方法，取消之前绑定的 mousemove 事件，但发现事件并未被成功移除。

初始代码示例 (问题代码):

<template>
  <div ref="myDiv" @mousemove="onMouseMove">这是一个Div</div>
  <button @click="removeListener">取消监听</button>
</template>

<script setup>
import { ref } from 'vue';

const myDiv = ref(null);

const onMouseMove = (event) => {
  console.log('鼠标正在移动...', event.clientX);
};

const removeListener = () => {
  if (myDiv.value) {
    // 尝试移除事件监听，但这里不会生效
    myDiv.value.removeEventListener('mousemove', onMouseMove);
    console.log('已尝试取消监听');
  }
};
</script>

问题根源：Vue 的事件处理机制

当你使用 @ 或 v-on 在模板中绑定事件时，Vue 并不会直接将你提供的函数 (onMouseMove) 作为原始的回调函数绑定到 DOM 元素上。

为了处理内部逻辑（例如，事件修饰符 .stop, .prevent，或内部的性能优化和缓存机制），Vue 会对你的事件函数进行一次“包装”。

Vue 内部的实际操作（概念解释）：

// 你提供的方法
const yourHandler = onMouseMove;

// Vue 内部创建的包装函数
const vueInternalHandler = function(event) {
  // ... Vue 内部的一些逻辑处理 ...
  // 在这里调用你真正的方法
  yourHandler(event);
};

// Vue 实际绑定到 DOM 上的是这个包装后的函数
element.addEventListener('mousemove', vueInternalHandler);

因此，当你调用 removeEventListener('mousemove', onMouseMove) 时，你试图移除的是 onMouseMove 这个函数。然而，浏览器中实际监听 mousemove 事件的函数是 vueInternalHandler。由于这两个函数的引用不同，removeEventListener 无法找到匹配的监听器，导致移除失败。

关键点: removeEventListener 要求传入的函数引用必须与 addEventListener 添加时传入的函数引用完全一致。

解决方案

针对这个问题，有两种推荐的解决方法：

方法一：手动绑定和移除原生事件

如果你需要精确地控制事件的添加和移除，最直接的方法是绕过 Vue 的模板事件绑定，直接在 <script> 中使用原生的 addEventListener 和 removeEventListener。

推荐实践: 在 onMounted 生命周期钩子中绑定事件，在 onBeforeUnmount 中销毁事件，以防止内存泄漏。

代码示例:

<template>
  <div ref="myDiv">这是一个Div</div>
  <button @click="removeListener">取消监听</button>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';

const myDiv = ref(null);

const onMouseMove = (event) => {
  console.log('鼠标正在移动...', event.clientX);
};

const removeListener = () => {
  if (myDiv.value) {
    myDiv.value.removeEventListener('mousemove', onMouseMove);
    console.log('监听已成功取消！');
  }
};

onMounted(() => {
  if (myDiv.value) {
    myDiv.value.addEventListener('mousemove', onMouseMove);
  }
});

// 推荐：在组件销毁前自动清理事件，防止内存泄漏
onBeforeUnmount(() => {
  removeListener();
});
</script>

方法二：使用组合式函数库 (VueUse)

VueUse 是一个非常流行的 Vue 组合式函数库，它提供了大量实用的工具，其中包括 useEventListener。这个函数极大地简化了事件监听的管理。

useEventListener 会自动处理事件的添加，并返回一个停止函数。它还会在组件卸载时自动清理事件，非常安全和方便。

代码示例:

<template>
  <div ref="myDiv">这是一个Div</div>
  <button @click="stop">取消监听 (VueUse)</button>
</template>

<script setup>
import { ref } from 'vue';
import { useEventListener } from '@vueuse/core';

const myDiv = ref(null);

const onMouseMove = (event) => {
  console.log('鼠标正在移动 (VueUse)...', event.clientX);
};

// useEventListener 会返回一个 stop 函数，用于停止监听
const stop = useEventListener(myDiv, 'mousemove', onMouseMove);
</script>

在这个例子中，只需调用 useEventListener 返回的 stop 函数，即可随时取消监听。

总结

1. 问题: 在模板中用 @ 绑定的事件，无法通过 removeEventListener + 原始函数引用的方式移除。
2. 原因: Vue 会包装事件处理函数，导致 addEventListener 和 removeEventListener 接收的函数引用不一致。
3. 解决方案:
   • 手动管理: 在 script 中通过 addEventListener 手动绑定，并保存函数引用以便后续移除。
   • 使用 VueUse: 借助 useEventListener 等成熟的组合式函数来自动化管理事件的生命周期，代码更简洁、健壮。