EventTarget: removeEventListener() 方法

注意：此功能在Web Workers中可用。

removeEventListener()是EventTarget接口的方法，用于从目标中移除之前使用EventTarget.addEventListener()注册的事件监听器。要移除的事件监听器是通过事件类型、事件监听器函数本身以及可能影响匹配过程的各种可选选项的组合来识别的；请参阅移除事件监听器的匹配。

如果使用不识别 EventTarget 上任何当前注册的事件监听器的参数调用 removeEventListener()，则不会产生任何影响。

如果在 EventTarget 的另一个监听器正在处理事件时，从 EventTarget 中移除了一个事件监听器，则该事件不会触发它。但是，它可以重新附加。

警告：如果一个监听器注册了两次，一次设置了捕获标志，另一次没有设置，则必须分别移除它们。移除捕获监听器不会影响同一监听器的非捕获版本，反之亦然。

事件监听器也可以通过将AbortSignal传递给addEventListener()，然后稍后在拥有该信号的控制器上调用abort()来移除。

语法

removeEventListener(type, listener)
removeEventListener(type, listener, options)
removeEventListener(type, listener, useCapture)

参数

type

一个字符串，指定要为其移除事件监听器的事件类型。

listener

要从事件目标中移除的事件处理程序的事件监听器函数。

options 可选

一个选项对象，指定事件监听器的特征。

可用的选项包括

capture: 一个布尔值，指定要移除的事件监听器是否注册为捕获监听器。如果此参数不存在，则假定默认值为 false。

useCapture 可选

一个布尔值，指定要移除的事件监听器是否注册为捕获监听器。如果此参数不存在，则假定默认值为 false。

返回值

无。

移除事件监听器的匹配

给定之前通过调用addEventListener()添加的事件监听器，您最终可能会到达需要移除它的点。显然，您需要为 removeEventListener() 指定相同的 type 和 listener 参数。但是 options 或 useCapture 参数呢？

虽然 addEventListener() 允许您为同一类型添加多次相同的监听器（如果选项不同），但 removeEventListener() 检查的唯一选项是 capture/useCapture 标志。它的值必须匹配才能使 removeEventListener() 匹配，但其他值则不匹配。

例如，考虑对 addEventListener() 的以下调用

element.addEventListener("mousedown", handleMouseDown, true);

现在考虑对 removeEventListener() 的这两个调用中的每一个

element.removeEventListener("mousedown", handleMouseDown, false); // Fails
element.removeEventListener("mousedown", handleMouseDown, true); // Succeeds

第一个调用失败，因为 useCapture 的值不匹配。第二个调用成功，因为 useCapture 匹配。

现在考虑以下情况

element.addEventListener("mousedown", handleMouseDown, { passive: true });

在这里，我们在其中 passive 设置为 true 的 options 对象中指定，而其他选项保留为默认值 false。

现在依次查看对 removeEventListener() 的每个调用。其中 capture 或 useCapture 为 true 的任何调用都失败；其他所有调用都成功。

只有 capture 设置对 removeEventListener() 有影响。

element.removeEventListener("mousedown", handleMouseDown, { passive: true }); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, { capture: false }); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, { capture: true }); // Fails
element.removeEventListener("mousedown", handleMouseDown, { passive: false }); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, false); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, true); // Fails

值得注意的是，一些浏览器版本在这方面不一致，除非您有其他具体原因，否则在调用 removeEventListener() 时，最好使用与调用 addEventListener() 时相同的数值。

示例

此示例演示如何添加基于 mouseover 的事件监听器，该监听器移除基于 click 的事件监听器。

const body = document.querySelector("body");
const clickTarget = document.getElementById("click-target");
const mouseOverTarget = document.getElementById("mouse-over-target");

let toggle = false;
function makeBackgroundYellow() {
  body.style.backgroundColor = toggle ? "white" : "yellow";

  toggle = !toggle;
}

clickTarget.addEventListener("click", makeBackgroundYellow, false);

mouseOverTarget.addEventListener("mouseover", () => {
  clickTarget.removeEventListener("click", makeBackgroundYellow, false);
});

规范

规范
DOM 标准 # ref-for-dom-eventtarget-removeeventlistener②

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

EventTarget.addEventListener()