EventTarget.removeEventListener() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

Die Methode removeEventListener() des EventTarget-Interfaces entfernt einen zuvor mit EventTarget.addEventListener() registrierten Event-Listener vom Ziel. Der zu entfernende Event-Listener wird über eine Kombination aus Event-Typ, Listener-Funktion selbst und verschiedenen optionalen Optionen identifiziert, die den Zuordnungsprozess beeinflussen können; siehe Passende Event-Listener zum Entfernen finden.

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

Wird ein Event-Listener von einem EventTarget entfernt, während ein anderer Listener des Ziels gerade ein Event verarbeitet, wird er von diesem Event nicht mehr ausgelöst. Er kann jedoch erneut angefügt werden.

Warnung: Wenn ein Listener zweimal registriert wurde – einmal mit gesetztem capture-Flag und einmal ohne – müssen Sie jeden einzeln entfernen. Das Entfernen eines capturing-Listeners betrifft nicht die non-capturing-Version desselben Listeners und umgekehrt.

Event-Listener können auch entfernt werden, indem man ein AbortSignal an ein addEventListener() übergibt und später abort() am Controller aufruft, dem das Signal gehört.

Passende Event-Listener zum Entfernen finden

Wenn ein zuvor mit addEventListener() hinzugefügter Event-Listener entfernt werden soll, müssen offensichtlich dieselben type- und listener-Parameter an removeEventListener() übergeben werden. Aber was ist mit den Parametern options bzw. useCapture?

Während addEventListener() es erlaubt, denselben Listener mehrmals für denselben Typ hinzuzufügen, sofern die Optionen sich unterscheiden, prüft removeEventListener() ausschließlich das capture/useCapture-Flag. Sein Wert muss übereinstimmen, damit removeEventListener() passt; die übrigen Werte spielen keine Rolle.

Betrachten Sie beispielsweise diesen Aufruf von addEventListener():

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

Bei einem Aufruf mit einem options-Objekt, in dem passive auf true gesetzt ist und alle anderen Optionen ihren Standardwert false behalten, schlagen alle removeEventListener()-Aufrufe fehl, bei denen capture bzw. useCapture true ist; alle anderen gelingen.

Für removeEventListener() ist ausschließlich die capture-Einstellung relevant.

Es sei angemerkt, dass sich einige Browser-Versionen hier inkonsistent verhalten haben, und sofern es keine speziellen Gründe dagegen gibt, ist es wahrscheinlich klug, beim Aufruf von removeEventListener() dieselben Werte zu verwenden wie beim Aufruf von addEventListener().

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string	—	Ein String, der den Typ des Events angibt, für den ein Event-Listener entfernt werden soll.
$listener Pflicht	Function	—	Die Event-Listener-Funktion des Event-Handlers, die vom Event-Target entfernt werden soll.
$options	Object	—	Ein options-Objekt, das Eigenschaften des Event-Listeners angibt. Verfügbare Option: capture (boolean) – gibt an, ob der zu entfernende Event-Listener als capturing-Listener registriert wurde. Fehlt dieser Parameter, wird der Standardwert false angenommen.
$useCapture	boolean	false	Ein boolescher Wert, der angibt, ob der zu entfernende Event-Listener als capturing-Listener registriert wurde. Fehlt dieser Parameter, wird der Standardwert false angenommen.

Rückgabewert

Typ

undefined

Beschreibung

Keiner.

Beispiele

addEventListener-Aufruf

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

Zwei removeEventListener-Aufrufe

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

Einen click-Listener per mouseover-Listener entfernen

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

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

// Wichtig · Fallstricke

Wenn ein Listener zweimal registriert wurde – einmal mit gesetztem capture-Flag und einmal ohne – muss jeder einzeln entfernt werden. Das Entfernen eines capturing-Listeners betrifft nicht die non-capturing-Version desselben Listeners und umgekehrt.

Siehe auch

EventTarget.addEventListener()