EventTarget: removeEventListener() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die removeEventListener() Methode des EventTarget-Interfaces entfernt einen zuvor mit EventTarget.addEventListener() registrierten Ereignis-Listener vom Ziel. Der zu entfernende Ereignis-Listener wird durch eine Kombination des Ereignistyps, der Ereignis-Listener-Funktion selbst und verschiedener optionaler Optionen identifiziert, die den Abgleichsprozess beeinflussen können; siehe Entsprechende Ereignis-Listener zur Entfernung.

Ein Aufruf von removeEventListener() mit Argumenten, die keinen aktuell registrierten Ereignis-Listener auf dem EventTarget identifizieren, hat keine Wirkung.

Wenn ein Ereignis-Listener von einem EventTarget entfernt wird, während ein anderer Listener des Ziels ein Ereignis verarbeitet, wird er nicht durch das Ereignis ausgelöst. Er kann jedoch neu angehängt werden.

Warnung: Wenn ein Listener zweimal registriert ist, einmal mit gesetztem capture-Flag und einmal ohne, müssen Sie jeden einzeln entfernen. Das Entfernen eines Capturing-Listeners wirkt sich nicht auf eine Nicht-Capturing-Version desselben Listeners aus und umgekehrt.

Ereignis-Listener können auch entfernt werden, indem ein AbortSignal an einen addEventListener() übergeben und dann später abort() auf dem Controller, der das Signal besitzt, aufgerufen wird.

Syntax

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

Parameter

type

Ein String, der den Typ des Ereignisses angibt, für das ein Ereignis-Listener entfernt werden soll.

listener

Die Ereignis-Listener-Funktion des zu entfernenden Ereignis-Handlers vom Ereignis-Ziel.

options Optional

Ein Optionsobjekt, das Merkmale des Ereignis-Listners angibt.

Die verfügbaren Optionen sind:

  • capture: Ein boolescher Wert, der angibt, ob der zu entfernende Ereignis-Listener als Capturing-Listener registriert ist oder nicht. Wenn dieser Parameter nicht vorhanden ist, wird der Standardwert false angenommen.
useCapture Optional

Ein boolescher Wert, der angibt, ob der zu entfernende Ereignis-Listener als Capturing-Listener registriert ist oder nicht. Wenn dieser Parameter nicht vorhanden ist, wird der Standardwert false angenommen.

Rückgabewert

Keiner.

Entsprechende Ereignis-Listener zur Entfernung

Angenommen, Sie haben einen Ereignis-Listener hinzugefügt, indem Sie addEventListener() aufgerufen haben, und möchten ihn schließlich entfernen. Offensichtlich müssen Sie die gleichen type- und listener-Parameter für removeEventListener() angeben. Aber was ist mit den Parametern options oder useCapture?

Auch wenn addEventListener() es Ihnen ermöglicht, denselben Listener mehrmals für denselben Typ hinzuzufügen, wenn die Optionen unterschiedlich sind, überprüft removeEventListener() nur das capture/useCapture-Flag. Sein Wert muss übereinstimmen, damit removeEventListener() übereinstimmt, aber die anderen Werte nicht.

Beispielsweise betrachten Sie diesen Aufruf von addEventListener():

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

Betrachten Sie nun jeden dieser beiden Aufrufe von removeEventListener():

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

Der erste Aufruf schlägt fehl, weil der Wert von useCapture nicht übereinstimmt. Der zweite gelingt, da useCapture übereinstimmt.

Nun betrachten Sie dies:

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

Hier geben wir ein options-Objekt an, bei dem passive auf true gesetzt ist, während die anderen Optionen auf den Standardwert false gesetzt bleiben.

Schauen Sie sich nun jeden dieser Aufrufe von removeEventListener() an. Jeder Aufruf, bei dem capture oder useCapture auf true gesetzt ist, schlägt fehl; alle anderen gelingen.

Nur die Einstellung capture ist wichtig für removeEventListener().

js
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

Es ist erwähnenswert, dass einige Browser-Versionen hier inkonsistent waren, und es ist wahrscheinlich klug, die gleichen Werte wie für den Aufruf von addEventListener() zu verwenden, wenn Sie removeEventListener() aufrufen, sofern Sie keine spezifischen Gründe dafür haben.

Beispiel

Dieses Beispiel zeigt, wie ein mouseover-basierter Ereignis-Listener hinzugefügt wird, der einen click-basierten Ereignis-Listener entfernt.

js
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);
});

Spezifikationen

Specification
DOM Standard
# ref-for-dom-eventtarget-removeeventlistener②

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch