EventTarget: Methode addEventListener()

Syntax

addEventListener(type, listener)
addEventListener(type, listener, options)
addEventListener(type, listener, useCapture)

Parameter

type

Eine Zeichenfolge, bei der die Gro- und Kleinschreibung beachtet wird und die den zu berwachenden Ereignistyp angibt.

listener

Das Objekt, das eine Benachrichtigung (ein Objekt, das die Schnittstelle Event implementiert) erhlt, wenn ein Ereignis des angegebenen Typs auftritt. Der Wert muss null, ein Objekt mit einer handleEvent()-Methode oder eine JavaScript-Funktion sein. Einzelheiten zum Callback selbst finden Sie unter Der Event-Listener-Callback.

options Optional

Ein Objekt, das Eigenschaften des Event-Listeners festlegt. Folgende Optionen sind verfgbar:

capture Optional

Ein boolescher Wert, der angibt, dass Ereignisse dieses Typs an den registrierten listener bermittelt werden, bevor sie an ein darunter liegendes EventTarget im DOM-Baum bermittelt werden. Ist die Option nicht angegeben, ist der Standardwert false.

once Optional

Ein boolescher Wert, der angibt, dass der listener nach dem Hinzufgen hchstens einmal aufgerufen werden soll. Bei true wird der listener beim Aufruf automatisch entfernt. Ist die Option nicht angegeben, ist der Standardwert false.

passive Optional

Ein boolescher Wert, der bei true angibt, dass die durch listener angegebene Funktion niemals preventDefault() aufruft. Ruft ein passiver Listener preventDefault() auf, hat dies keine Wirkung und mglicherweise wird eine Warnung in der Konsole ausgegeben.

Ist diese Option nicht angegeben, ist ihr Standardwert false mit Ausnahme von wheel-, mousewheel-, touchstart- und touchmove-Ereignissen auf Window, Document, Document.documentElement und Document.body. Fr diese ist der Standardwert true. Weitere Informationen finden Sie unter Passive Listener verwenden.

signal Optional

Ein AbortSignal. Der Listener wird entfernt, wenn die Methode abort() des AbortController aufgerufen wird, zu dem das AbortSignal gehrt. Ist die Option nicht angegeben, ist dem Listener kein AbortSignal zugeordnet.

useCapture Optional

Ein boolescher Wert, der angibt, ob Ereignisse dieses Typs an den registrierten listener bermittelt werden, bevor sie an ein darunter liegendes EventTarget im DOM-Baum bermittelt werden. Ereignisse, die sich durch den Baum nach oben ausbreiten, lsen keinen Listener aus, der Capturing verwendet. Bubbling und Capturing sind zwei Arten der Ausbreitung von Ereignissen, die in einem Element auftreten, das in einem anderen Element verschachtelt ist, wenn beide Elemente einen Handler fr das Ereignis registriert haben. Der Modus der Ereignisausbreitung bestimmt, in welcher Reihenfolge die Elemente das Ereignis empfangen. Eine ausfhrliche Erklrung finden Sie in der DOM-Spezifikation und unter Reihenfolge von JavaScript-Ereignissen. Ist useCapture nicht angegeben, ist der Standardwert false.

Hinweis: Bei Event-Listenern, die am Ereignisziel registriert sind, befindet sich das Ereignis in der Zielphase und nicht in der Capturing- oder Bubbling-Phase. Event-Listener in der Capturing-Phase werden vor Event-Listenern in der Ziel- und Bubbling-Phase aufgerufen.

wantsUntrusted Optional

Ein Firefox-(Gecko-)spezifischer Parameter. Bei true empfngt der Listener synthetische Ereignisse, die von Webinhalten ausgelst werden (der Standardwert ist false fr Browser-Chrome und true fr gewhnliche Webseiten). Dieser Parameter ist fr Code in Add-ons sowie im Browser selbst ntzlich.

Rckgabewert

Keiner (undefined).

Hinweise zur Verwendung

Der Event-Listener-Callback

Ein Event-Listener kann entweder als Callback-Funktion oder als Objekt angegeben werden, dessen handleEvent()-Methode als Callback-Funktion dient.

Die Callback-Funktion selbst hat dieselben Parameter und denselben Rckgabewert wie die Methode handleEvent(): Sie akzeptiert einen einzelnen Parameter ein von Event abgeleitetes Objekt, das das aufgetretene Ereignis beschreibt und gibt nichts zurck.

Ein Event-Handler-Callback, der sowohl fullscreenchange als auch fullscreenerror verarbeiten kann, knnte beispielsweise so aussehen:

function handleEvent(event) {
  if (event.type === "fullscreenchange") {
    /* handle a full screen toggle */
  } else {
    /* handle a full screen toggle error */
  }
}

Der Wert von this innerhalb des Handlers

Hufig soll auf das Element zugegriffen werden, auf dem der Event-Handler ausgelst wurde, etwa wenn ein allgemeiner Handler fr mehrere hnliche Elemente verwendet wird.

Wird eine Handler-Funktion mit addEventListener() an ein Element gebunden, verweist this innerhalb des Handlers auf dieses Element. Der Wert entspricht dem der Eigenschaft currentTarget des Ereignisarguments, das an den Handler bergeben wird.

myElement.addEventListener("click", function (e) {
  console.log(this.className); // logs the className of myElement
  console.log(e.currentTarget === this); // logs `true`
});

Zur Erinnerung: Pfeilfunktionen haben keinen eigenen this-Kontext.

myElement.addEventListener("click", (e) => {
  console.log(this.className); // WARNING: `this` is not `myElement`
  console.log(e.currentTarget === this); // logs `false`
});

Wird ein Event-Handler (beispielsweise onclick) im HTML-Quelltext an einem Element angegeben, wird der JavaScript-Code im Attributwert intern in eine Handler-Funktion eingebettet, die den Wert von this auf eine mit addEventListener() konsistente Weise bindet. Ein this innerhalb dieses Codes verweist auf das Element.

<table id="my-table" >
  <!-- `this` refers to the table; logs 'my-table' -->
  
</table>

Beachten Sie, dass sich der Wert von this innerhalb einer Funktion, die vom Code im Attributwert aufgerufen wird, nach den blichen Regeln richtet. Das folgende Beispiel zeigt dies:

<script>
  function logID() {
    console.log(this.id);
  }
</script>
<table id="my-table" >
  <!-- when called, `this` will refer to the global object -->
  
</table>

Innerhalb von logID() verweist this auf das globale Objekt Window (oder hat im Strict Mode den Wert undefined).

this mit bind() festlegen

Mit der Methode Function.prototype.bind() knnen Sie einen festen this-Kontext fr alle spteren Aufrufe festlegen. So vermeiden Sie Probleme, wenn unklar ist, welchen Wert this abhngig vom Aufrufkontext der Funktion haben wird. Beachten Sie jedoch, dass Sie eine Referenz auf den Listener behalten mssen, damit Sie ihn spter entfernen knnen.

Dies ist ein Beispiel mit und ohne bind():

class Something {
  name = "Something Good";
  constructor(element) {
    // bind causes a fixed `this` context to be assigned to `onclick2`
    this.onclick2 = this.onclick2.bind(this);
    element.addEventListener("click", this.onclick1);
    element.addEventListener("click", this.onclick2); // Trick
  }
  onclick1(event) {
    console.log(this.name); // undefined, as `this` is the element
  }
  onclick2(event) {
    console.log(this.name); // 'Something Good', as `this` is bound to the Something instance
  }
}

const s = new Something(document.body);

Eine weitere Mglichkeit besteht darin, Ereignisse mit einer speziellen Funktion namens handleEvent() abzufangen:

class Something {
  name = "Something Good";
  constructor(element) {
    // Note that the listeners in this case are `this`, not this.handleEvent
    element.addEventListener("click", this);
    element.addEventListener("dblclick", this);
  }
  handleEvent(event) {
    console.log(this.name); // 'Something Good', as this is bound to newly created object
    switch (event.type) {
      case "click":
        // some code here
        break;
      case "dblclick":
        // some code here
        break;
    }
  }
}

const s = new Something(document.body);

Eine andere Mglichkeit, mit der Referenz von this umzugehen, ist eine Pfeilfunktion, die keinen eigenen this-Kontext erzeugt.

class SomeClass {
  name = "Something Good";

  register() {
    window.addEventListener("keydown", (e) => {
      this.someMethod(e);
    });
  }

  someMethod(e) {
    console.log(this.name);
    switch (e.code) {
      case "ArrowUp":
        // some code here
        break;
      case "ArrowDown":
        // some code here
        break;
    }
  }
}

const myObject = new SomeClass();
myObject.register();

Daten an einen Event-Listener bergeben und aus ihm erhalten

Event-Listener akzeptieren nur ein Argument: ein Event oder eine Unterklasse von Event. Dieses Argument wird automatisch an den Listener bergeben; der Rckgabewert wird ignoriert. Um Daten an einen Event-Listener zu bergeben und aus ihm zu erhalten, mssen Sie daher Closures verwenden, statt die Daten ber Parameter und Rckgabewerte auszutauschen.

Die als Event-Listener bergebenen Funktionen haben Zugriff auf alle Variablen, die in den ueren Gltigkeitsbereichen deklariert sind, welche die Funktion umschlieen.

const myButton = document.getElementById("my-button-id");
let someString = "Data";

myButton.addEventListener("click", () => {
  console.log(someString);
  // 'Data' on first click,
  // 'Data Again' on second click

  someString = "Data Again";
});

console.log(someString); // Expected Value: 'Data' (will never output 'Data Again')

Weitere Informationen zu den Gltigkeitsbereichen von Funktionen finden Sie im Leitfaden zu Funktionen.

Speicherprobleme

const elems = document.getElementsByTagName("*");

// Case 1
for (const elem of elems) {
  elem.addEventListener("click", (e) => {
    // Do something
  });
}

// Case 2
function processEvent(e) {
  // Do something
}

for (const elem of elems) {
  elem.addEventListener("click", processEvent);
}

Im ersten Fall oben wird bei jedem Schleifendurchlauf eine neue (anonyme) Handler-Funktion erstellt. Im zweiten Fall wird dieselbe zuvor deklarierte Funktion als Event-Handler verwendet. Das verbraucht weniger Speicher, da nur eine Handler-Funktion erstellt wird. Auerdem lsst sich im ersten Fall removeEventListener() nicht aufrufen, weil keine Referenz auf die anonyme Funktion erhalten bleibt (beziehungsweise hier auf keine der mehreren anonymen Funktionen, die die Schleife mglicherweise erstellt). Im zweiten Fall ist der Aufruf von myElement.removeEventListener("click", processEvent, false) mglich, da processEvent die Funktionsreferenz ist.

Im Hinblick auf den Speicherverbrauch ist das eigentliche Problem nicht, dass keine Funktionsreferenz erhalten bleibt, sondern dass keine statische Funktionsreferenz erhalten bleibt.

Passive Listener verwenden

Hat ein Ereignis eine Standardaktion beispielsweise ein wheel-Ereignis, das standardmig den Container scrollt , kann der Browser diese Aktion im Allgemeinen erst starten, wenn der Event-Listener beendet ist. Der Browser wei vorher nicht, ob der Listener die Standardaktion durch einen Aufruf von Event.preventDefault() verhindern wird. Dauert die Ausfhrung des Listeners zu lange, kann dies eine merkliche Verzgerung verursachen, auch Jank genannt, bevor die Standardaktion ausgefhrt werden kann.

Indem ein Event-Listener die Option passive auf true setzt, erklrt er, dass er die Standardaktion nicht verhindern wird. Der Browser kann sie daher sofort starten, ohne auf das Ende des Listeners zu warten. Ruft der Listener dennoch Event.preventDefault() auf, bleibt dies wirkungslos.

Damit auch bestehender Code von der besseren Scroll-Leistung passiver Listener profitiert, legt die Spezifikation fr addEventListener() den Standardwert der Option passive fr wheel-, mousewheel-, touchstart- und touchmove-Ereignisse auf Window, Document, Document.documentElement und Document.body auf true fest. Fr andere Ereignisse und Ziele ist der Standardwert false. Ein passiver Listener kann das Ereignis nicht abbrechen, sodass der Browser nicht auf sein Ende warten muss, bevor er scrollt.

Wenn Sie dieses Verhalten berschreiben und sicherstellen mchten, dass die Option passive den Wert false hat, mssen Sie sie deshalb ausdrcklich auf false setzen, statt sich auf den Standardwert zu verlassen.

Bei einem einfachen scroll-Ereignis mssen Sie sich ber den Wert von passive keine Gedanken machen. Da dieses Ereignis nicht abgebrochen werden kann, knnen Event-Listener die Darstellung der Seite ohnehin nicht blockieren.

Ein Beispiel fr die Auswirkungen passiver Listener finden Sie unter Scroll-Leistung mit passiven Listenern verbessern.

Beispiele

Einen einfachen Listener hinzufgen

Dieses Beispiel zeigt, wie Sie mit addEventListener() Mausklicks auf einem Element berwachen.

HTML

<table id="outside">
  <tbody>
    <tr>
      <td id="t1">one</td>
    </tr>
    <tr>
      <td id="t2">two</td>
    </tr>
  </tbody>
</table>

JavaScript

// Function to change the content of t2
function modifyText() {
  const t2 = document.getElementById("t2");
  const isNodeThree = t2.firstChild.nodeValue === "three";
  t2.firstChild.nodeValue = isNodeThree ? "two" : "three";
}

// Add event listener to table
const el = document.getElementById("outside");
el.addEventListener("click", modifyText);

In diesem Code ist modifyText() ein mit addEventListener() registrierter Listener fr click-Ereignisse. Ein Klick an beliebiger Stelle in der Tabelle breitet sich zum Handler aus und fhrt modifyText() aus.

Ergebnis

Einen abbrechbaren Listener hinzufgen

Dieses Beispiel zeigt, wie Sie mit addEventListener() einen Listener hinzufgen, der sich mit einem AbortSignal abbrechen lsst.

HTML

<table id="outside">
  <tbody>
    <tr>
      <td id="t1">one</td>
    </tr>
    <tr>
      <td id="t2">two</td>
    </tr>
  </tbody>
</table>

JavaScript

// Add an abortable event listener to table
const controller = new AbortController();
const el = document.getElementById("outside");
el.addEventListener("click", modifyText, { signal: controller.signal });

// Function to change the content of t2
function modifyText() {
  const t2 = document.getElementById("t2");
  if (t2.firstChild.nodeValue === "three") {
    t2.firstChild.nodeValue = "two";
  } else {
    t2.firstChild.nodeValue = "three";
    controller.abort(); // remove listener after value reaches "three"
  }
}

Im obigen Beispiel ndern wir den Code des vorherigen Beispiels so, dass wir abort() auf dem AbortController aufrufen, den wir an addEventListener() bergeben haben, nachdem sich der Inhalt der zweiten Zeile in three gendert hat. Dadurch bleibt der Wert dauerhaft three, weil nun kein Code mehr auf ein Klickereignis wartet.

Ergebnis

Event-Listener mit anonymer Funktion

Hier sehen wir uns an, wie Sie mit einer anonymen Funktion Parameter an einen Event-Listener bergeben knnen.

HTML

<table id="outside">
  <tbody>
    <tr>
      <td id="t1">one</td>
    </tr>
    <tr>
      <td id="t2">two</td>
    </tr>
  </tbody>
</table>

JavaScript

// Function to change the content of t2
function modifyText(newText) {
  const t2 = document.getElementById("t2");
  t2.firstChild.nodeValue = newText;
}

// Function to add event listener to table
const el = document.getElementById("outside");
el.addEventListener("click", function () {
  modifyText("four");
});

Beachten Sie, dass der Listener eine anonyme Funktion ist, die Code enthlt, der seinerseits Parameter an die Funktion modifyText() bergeben kann. Diese Funktion verarbeitet das Ereignis.

Ergebnis

Event-Listener mit Pfeilfunktion

Dieses Beispiel zeigt einen Event-Listener, der mit einer Pfeilfunktion implementiert wurde.

HTML

<table id="outside">
  <tbody>
    <tr>
      <td id="t1">one</td>
    </tr>
    <tr>
      <td id="t2">two</td>
    </tr>
  </tbody>
</table>

JavaScript

// Function to change the content of t2
function modifyText(newText) {
  const t2 = document.getElementById("t2");
  t2.firstChild.nodeValue = newText;
}

// Add event listener to table with an arrow function
const el = document.getElementById("outside");
el.addEventListener("click", () => {
  modifyText("four");
});

Ergebnis

Beachten Sie, dass anonyme Funktionen und Pfeilfunktionen zwar hnlich sind, this aber unterschiedlich binden. Whrend anonyme Funktionen (und alle herkmmlichen JavaScript-Funktionen) eine eigene Bindung fr this erzeugen, bernehmen Pfeilfunktionen die this-Bindung der umschlieenden Funktion.

Das bedeutet, dass die Variablen und Konstanten, die der umschlieenden Funktion zur Verfgung stehen, bei Verwendung einer Pfeilfunktion auch dem Event-Handler zur Verfgung stehen.

Beispiel fr die Verwendung von Optionen

HTML

<div class="outer">
  outer, once & none-once
  <div class="middle" target="_blank">
    middle, capture & none-capture
    <a class="inner1" href="https://www.mozilla.org" target="_blank">
      inner1, passive & preventDefault(which is not allowed)
    </a>
    <a class="inner2" href="https://developer.mozilla.org/" target="_blank">
      inner2, none-passive & preventDefault(not open new page)
    </a>
  </div>
</div>
<hr />
<button class="clear-button">Clear logs</button>
<section class="demo-logs"></section>

CSS

.outer,
.middle,
.inner1,
.inner2 {
  display: block;
  width: 520px;
  padding: 15px;
  margin: 15px;
  text-decoration: none;
}
.outer {
  border: 1px solid red;
  color: red;
}
.middle {
  border: 1px solid green;
  color: green;
  width: 460px;
}
.inner1,
.inner2 {
  border: 1px solid purple;
  color: purple;
  width: 400px;
}

.demo-logs {
  width: 530px;
  height: 16rem;
  background-color: #dddddd;
  overflow-x: auto;
  padding: 1rem;
}

JavaScript

const clearBtn = document.querySelector(".clear-button");
const demoLogs = document.querySelector(".demo-logs");

function log(msg) {
  demoLogs.innerText += `${msg}\n`;
}

clearBtn.addEventListener("click", () => {
  demoLogs.innerText = "";
});

const outer = document.querySelector(".outer");
const middle = document.querySelector(".middle");
const inner1 = document.querySelector(".inner1");
const inner2 = document.querySelector(".inner2");

const capture = {
  capture: true,
};
const noneCapture = {
  capture: false,
};
const once = {
  once: true,
};
const noneOnce = {
  once: false,
};
const passive = {
  passive: true,
};
const nonePassive = {
  passive: false,
};

outer.addEventListener("click", onceHandler, once);
outer.addEventListener("click", noneOnceHandler, noneOnce);
middle.addEventListener("click", captureHandler, capture);
middle.addEventListener("click", noneCaptureHandler, noneCapture);
inner1.addEventListener("click", passiveHandler, passive);
inner2.addEventListener("click", nonePassiveHandler, nonePassive);

function onceHandler(event) {
  log("outer, once");
}
function noneOnceHandler(event) {
  log("outer, none-once, default\n");
}
function captureHandler(event) {
  // event.stopImmediatePropagation();
  log("middle, capture");
}
function noneCaptureHandler(event) {
  log("middle, none-capture, default");
}
function passiveHandler(event) {
  // Unable to preventDefault inside passive event listener invocation.
  event.preventDefault();
  log("inner1, passive, open new page");
}
function nonePassiveHandler(event) {
  event.preventDefault();
  // event.stopPropagation();
  log("inner2, none-passive, default, not open new page");
}

Ergebnis

Klicken Sie nacheinander auf den ueren, mittleren und inneren Container, um zu sehen, wie die Optionen funktionieren.

Event-Listener mit mehreren Optionen

Sie knnen im Parameter options mehrere Optionen festlegen. Im folgenden Beispiel legen wir zwei Optionen fest:

• passive, um anzugeben, dass der Handler preventDefault() nicht aufrufen wird.
• once, um sicherzustellen, dass der Event-Handler nur einmal aufgerufen wird.

HTML

<button id="example-button">You have not clicked this button.</button>
<button id="reset-button">Click this button to reset the first button.</button>

JavaScript

const buttonToBeClicked = document.getElementById("example-button");

const resetButton = document.getElementById("reset-button");

// the text that the button is initialized with
const initialText = buttonToBeClicked.textContent;

// the text that the button contains after being clicked
const clickedText = "You have clicked this button.";

// we hoist the event listener callback function
// to prevent having duplicate listeners attached
function eventListener() {
  buttonToBeClicked.textContent = clickedText;
}

function addListener() {
  buttonToBeClicked.addEventListener("click", eventListener, {
    passive: true,
    once: true,
  });
}

// when the reset button is clicked, the example button is reset,
// and allowed to have its state updated again
resetButton.addEventListener("click", () => {
  buttonToBeClicked.textContent = initialText;
  addListener();
});

addListener();

Ergebnis

Scroll-Leistung mit passiven Listenern verbessern

Das folgende Beispiel zeigt die Wirkung der Option passive. Es enthlt ein <div> mit etwas Text sowie ein Kontrollkstchen.

HTML

<div id="container">
  <p>
    But down there it would be dark now, and not the lovely lighted aquarium she
    imagined it to be during the daylight hours, eddying with schools of tiny,
    delicate animals floating and dancing slowly to their own serene currents
    and creating the look of a living painting. That was wrong, in any case. The
    ocean was different from an aquarium, which was an artificial environment.
    The ocean was a world. And a world is not art. Dorothy thought about the
    living things that moved in that world: large, ruthless and hungry. Like us
    up here.
  </p>
</div>

<div>
  <input type="checkbox" id="passive" name="passive" checked />
  <label for="passive">passive</label>
</div>

#container {
  width: 150px;
  height: 200px;
  overflow: scroll;
  margin: 2rem 0;
  padding: 0.4rem;
  border: 1px solid black;
}

JavaScript

Der Code fgt einen Listener fr das wheel-Ereignis des Containers hinzu, das den Container standardmig scrollt. Der Listener fhrt einen langwierigen Vorgang aus. Anfangs wird der Listener mit der Option passive hinzugefgt. Bei jeder nderung des Kontrollkstchens schaltet der Code die Option passive um.

const passive = document.querySelector("#passive");
const container = document.querySelector("#container");

passive.addEventListener("change", (event) => {
  container.removeEventListener("wheel", wheelHandler);
  container.addEventListener("wheel", wheelHandler, {
    passive: passive.checked,
    once: true,
  });
});

container.addEventListener("wheel", wheelHandler, {
  passive: true,
  once: true,
});

function wheelHandler() {
  function isPrime(n) {
    for (let c = 2; c <= Math.sqrt(n); ++c) {
      if (n % c === 0) {
        return false;
      }
    }
    return true;
  }

  const quota = 1000000;
  const primes = [];
  const maximum = 1000000;

  while (primes.length < quota) {
    const candidate = Math.floor(Math.random() * (maximum + 1));
    if (isPrime(candidate)) {
      primes.push(candidate);
    }
  }

  console.log(primes);
}

Ergebnis

Das hat folgende Auswirkungen:

• Anfangs ist der Listener passiv. Wenn Sie versuchen, den Container mit dem Mausrad zu scrollen, reagiert er sofort.
• Wenn Sie passive deaktivieren und versuchen, den Container mit dem Mausrad zu scrollen, tritt eine merkliche Verzgerung auf, bevor der Container scrollt. Der Browser muss auf das Ende des langwierigen Listeners warten.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• EventTarget.removeEventListener()
• Benutzerdefinierte Ereignisse erstellen und auslsen
• Weitere Informationen zur Verwendung von this in Event-Handlern