EventTarget: Methode addEventListener()

Syntax

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

Parameter

type

Ein auf Groß- und Kleinschreibung achtender String, der den Ereignistyp darstellt, auf den gehört werden soll.

listener

Das Objekt, das eine Benachrichtigung erhält (ein Objekt, das die Event-Schnittstelle implementiert), wenn ein Ereignis des angegebenen Typs eintritt. Dieses muss null, ein Objekt mit einer handleEvent()-Methode oder eine JavaScript-Funktion sein. Siehe Der Event-Listener-Callback für Details zum Callback selbst.

options Optional

Ein Objekt, das Merkmale über den Event-Listener angibt. Die verfügbaren Optionen sind:

capture Optional

Ein boolescher Wert, der angibt, dass Ereignisse dieses Typs an den registrierten listener gesendet werden, bevor sie an ein untergeordnetes EventTarget im DOM-Baum gesendet werden. Wenn nicht angegeben, ist der Standardwert false.

once Optional

Ein boolescher Wert, der angibt, dass der listener höchstens einmal nach dem Hinzufügen aufgerufen werden soll. Wenn true, wird der listener automatisch entfernt, wenn er aufgerufen wird. Wenn nicht angegeben, ist der Standardwert false.

passive Optional

Ein boolescher Wert, der, wenn true, angibt, dass die von listener angegebene Funktion niemals preventDefault() aufrufen wird. Wenn ein passiver Listener preventDefault() aufruft, passiert nichts und es kann eine Konsolenwarnung generiert werden.

Wenn diese Option nicht angegeben ist, ist der Standardwert false – außer in Browsern außer Safari, wo der Standardwert für wheel, mousewheel, touchstart und touchmove Ereignisse true ist. Siehe Verwendung passiver Listener, um mehr zu erfahren.

signal Optional

Ein AbortSignal. Der Listener wird entfernt, wenn die Methode abort() des AbortController, der das AbortSignal besitzt, aufgerufen wird. Wenn nicht angegeben, ist kein AbortSignal mit dem Listener verknüpft.

useCapture Optional

Ein boolescher Wert, der angibt, ob Ereignisse dieses Typs an den registrierten listener vor dem Dispatch an ein beliebiges untergeordnetes EventTarget im DOM-Baum gesendet werden. Ereignisse, die durch den Baum aufsteigen, lösen keinen Listener aus, der für die Verwendung von Capture vorgesehen ist. Event bubbling und capturing sind zwei Möglichkeiten der Ereignisausbreitung, die bei einem Element auftreten, das innerhalb eines anderen verschachtelt ist, wenn beide Elemente einen Handler für das Ereignis registriert haben. Der Ereignisausbreitungsmodus bestimmt die Reihenfolge, in der Elemente das Ereignis empfangen. Siehe die DOM-Spezifikation und JavaScript-Ereignisreihenfolge für eine ausführliche Erklärung. Wenn nicht angegeben, ist useCapture standardmäßig false.

Hinweis: Bei Event-Listenern, die an das Ereignisziel angeschlossen sind, befinden sich die Ereignisse in der Zielphase, nicht in den Capturing- und Bubbling-Phasen. Event-Listener in der Capturing-Phase werden vor den Event-Listenern in der Ziel- und Bubbling-Phase aufgerufen.

wantsUntrusted Optional Nicht standardisiert

Ein Firefox (Gecko)-spezifischer Parameter. Wenn true, empfängt der Listener synthetische Ereignisse, die vom Webinhalt gesendet werden (der Standardwert ist false für den Browser chrome und true für reguläre Webseiten). Dieser Parameter ist nützlich für Code, der in Add-ons sowie im Browser selbst zu finden ist.

Rückgabewert

Keiner (undefined).

Verwendungshinweise

Der Event-Listener-Callback

Der 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 Rückgabewerte wie die handleEvent()-Methode; das heißt, der Callback akzeptiert einen einzigen Parameter: ein Objekt basierend auf Event, das das eingetretene Ereignis beschreibt, und gibt nichts zurück.

Zum Beispiel könnte ein Event-Handler-Callback, der sowohl das fullscreenchange- als auch das fullscreenerror-Ereignis behandelt, folgendermaßen 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

Es ist oft wünschenswert, auf das Element zu verweisen, auf dem der Event-Handler ausgelöst wurde, zum Beispiel bei der Verwendung eines generischen Handlers für eine Reihe ähnlicher Elemente.

Wenn eine Handler-Funktion an ein Element mithilfe von addEventListener() angehängt wird, ist der Wert von this innerhalb des Handlers eine Referenz auf das Element. Er ist derselbe wie der Wert der currentTarget-Eigenschaft des Ereignisarguments, das an den Handler übergeben wird.

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

Zur Erinnerung: Arrow-Funktionen haben keinen eigenen this-Kontext.

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

Wenn ein Event-Handler (zum Beispiel onclick) in der HTML-Quelle an ein Element angehängt wird, wird der JavaScript-Code im Attributwert effektiv in eine Handler-Funktion eingebunden, die den Wert von this in einer Weise bindet, die mit addEventListener() übereinstimmt; ein Vorkommen von this innerhalb des Codes stellt eine Referenz auf das Element dar.

<table id="my_table" onclick="console.log(this.id);">
  <!-- `this` refers to the table; logs 'my_table' -->
  …
</table>

Beachten Sie, dass der Wert von this innerhalb einer Funktion, die vom Code im Attributwert aufgerufen wird, sich gemäß den Standardregeln verhält. Dies wird im folgenden Beispiel gezeigt:

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

Der Wert von this innerhalb von logID() ist eine Referenz auf das globale Objekt Window (oder undefined im Fall von Strict Mode.

Spezifizieren von "this" mit bind()

Die Methode Function.prototype.bind() ermöglicht es Ihnen, einen festen this-Kontext für alle nachfolgenden Aufrufe festzulegen – und umgeht Probleme, bei denen unklar ist, was this sein wird, abhängig von dem Kontext, aus dem Ihre Funktion aufgerufen wurde. Beachten Sie jedoch, dass Sie eine Referenz auf den Listener behalten müssen, damit Sie ihn später entfernen können.

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 andere Lösung besteht darin, eine spezielle Funktion namens handleEvent() zu verwenden, um alle Ereignisse 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 weitere Möglichkeit, den Bezug zu this zu behandeln, ist die Verwendung einer Arrow-Funktion, die keinen separaten this-Kontext erstellt.

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 in und aus einem Event-Listener erhalten

Event-Listener nehmen nur ein Argument entgegen, ein Event oder eine Unterklasse von Event, das automatisch an den Listener übergeben wird, und der Rückgabewert wird ignoriert. Um Daten in und aus einem Event-Listener zu erhalten, müssen Sie daher anstelle des Durchreichens der Daten durch Parameter und Rückgabewerte Closures erstellen.

Die als Event-Listener übergebenen Funktionen haben Zugriff auf alle Variablen, die in den äußeren Bereichen deklariert sind, die die Funktion enthalten.

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

Lesen Sie den Funktionsleitfaden für weitere Informationen zu Funktionsbereichen.

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 obigen Fall wird mit jeder Iteration der Schleife eine neue (anonyme) Handler-Funktion erstellt. Im zweiten Fall wird dieselbe vorher deklarierte Funktion als Event-Handler verwendet, was zu geringeren Speichernutzung führt, da nur eine Handler-Funktion erstellt wird. Darüber hinaus ist es im ersten Fall nicht möglich, removeEventListener() aufzurufen, da keine Referenz auf die anonyme Funktion aufbewahrt wird (oder hier, nicht auf eine der mehreren anonymen Funktionen, die die Schleife erstellen könnte). Im zweiten Fall ist es möglich, myElement.removeEventListener("click", processEvent, false) auszuführen, da processEvent die Funktionsreferenz ist.

Tatsächlich ist im Hinblick auf den Speicherverbrauch nicht das Fehlen einer Funktionsreferenz das eigentliche Problem, sondern das Fehlen einer statischen Funktionsreferenz.

Verwendung von passiven Listenern

Wenn ein Ereignis eine Standardaktion hat – zum Beispiel ein wheel-Ereignis, das standardmäßig das Container-Element scrollt – ist der Browser im Allgemeinen nicht in der Lage, die Standardaktion zu starten, bis der Event-Listener abgeschlossen ist, da er im Voraus nicht weiß, ob der Event-Listener die Standardaktion durch Aufrufen von Event.preventDefault() möglicherweise verhindern könnte. Wenn der Event-Listener zu lange dauert, um ausgeführt zu werden, kann dies eine spürbare Verzögerung verursachen, auch bekannt als Jank, bevor die Standardaktion ausgeführt werden kann.

Indem Sie die passive-Option auf true setzen, gibt ein Event-Listener an, dass er die Standardaktion nicht abbrechen wird, sodass der Browser die Standardaktion sofort starten kann, ohne darauf zu warten, dass der Listener fertig ist. Wenn der Listener dann Event.preventDefault() aufruft, hat dies keine Auswirkung.

Die Spezifikation für addEventListener() definiert den Standardwert für die passive-Option immer als false. Um jedoch die Scroll-Leistungsverbesserungen passiver Listener im Legacy-Code zu realisieren, haben moderne Browser den Standardwert der passive-Option für die wheel-, mousewheel-, touchstart- und touchmove-Ereignisse auf Dokumentebene wie Window, Document und Document.body geändert. Das verhindert, dass der Event-Listener das Ereignis abbricht, sodass er das Seitenrendering nicht blockieren kann, während der Benutzer scrollt.

Aus diesem Grund müssen Sie ausdrücklich die Option auf false setzen (anstatt auf den Standardwert zu vertrauen), wenn Sie dieses Verhalten überschreiben und sicherstellen möchten, dass die passive-Option false ist.

Sie müssen sich keine Sorgen um den Wert von passive für das grundlegende scroll-Ereignis machen. Da es nicht abgebrochen werden kann, können Event-Listener das Seitenrendering ohnehin nicht blockieren.

Siehe Verbesserung der Scroll-Leistung durch passive Listener für ein Beispiel, das die Wirkung passiver Listener zeigt.

Beispiele

Einen einfachen Listener hinzufügen

Dieses Beispiel zeigt, wie addEventListener() verwendet wird, um Mausklicks auf einem Element zu überwachen.

HTML

<table id="outside">
  <tr>
    <td id="t1">one</td>
  </tr>
  <tr>
    <td id="t2">two</td>
  </tr>
</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 Listener für click-Ereignisse, der mit addEventListener() registriert wurde. Ein Klick irgendwo in der Tabelle blubbert bis zum Handler und führt modifyText() aus.

Ergebnis

Einen abbrechbaren Listener hinzufügen

Dieses Beispiel zeigt, wie man addEventListener() verwendet, das mit einem AbortSignal abgebrochen werden kann.

HTML

<table id="outside">
  <tr>
    <td id="t1">one</td>
  </tr>
  <tr>
    <td id="t2">two</td>
  </tr>
</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 aus dem vorherigen Beispiel so, dass wir nach der zweiten Zeilenänderung des Inhalts auf "drei" abort() vom AbortController aufrufen, den wir an den addEventListener()-Aufruf übergeben haben. Das führt dazu, dass der Wert auf "drei" bleibt, da wir keinen Code mehr haben, der auf ein Klick-Ereignis hört.

Ergebnis

Event-Listener mit anonymer Funktion

Hier werden wir uns ansehen, wie man eine anonyme Funktion verwendet, um Parameter in den Event-Listener zu übergeben.

HTML

<table id="outside">
  <tr>
    <td id="t1">one</td>
  </tr>
  <tr>
    <td id="t2">two</td>
  </tr>
</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 kapselt, der dann imstande ist, Parameter an die modifyText()-Funktion zu senden, die für die eigentliche Reaktion auf das Ereignis verantwortlich ist.

Ergebnis

Event-Listener mit einer Arrow-Funktion

Dieses Beispiel zeigt einen Event-Listener, der mit der Arrow-Funktion-Notation implementiert ist.

HTML

<table id="outside">
  <tr>
    <td id="t1">one</td>
  </tr>
  <tr>
    <td id="t2">two</td>
  </tr>
</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

Bitte beachten Sie, dass wobei anonyme und Arrow-Funktionen ähnlich sind, sie unterschiedliche this-Bindungen haben. Während anonyme (und alle traditionellen JavaScript-Funktionen) ihre eigenen this-Bindungen erstellen, erben Arrow-Funktionen die this-Bindung der umgebenden Funktion.

Das bedeutet, dass die Variablen und Konstanten, die in der umgebenden Funktion verfügbar sind, auch dem Event-Handler beim Verwenden einer Arrow-Funktion zur Verfügung stehen.

Beispiel für 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 auf die äußeren, mittleren, inneren Container, um zu sehen, wie die Optionen funktionieren.

Event-Listener mit mehreren Optionen

Sie können mehr als eine der Optionen im options-Parameter festlegen. Im folgenden Beispiel setzen wir zwei Optionen:

• passive, um sicherzustellen, dass der Handler nicht preventDefault() aufruft
• 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

Verbesserung der Scroll-Leistung durch passive Listener

Das folgende Beispiel zeigt die Wirkung der Einstellung passive. Es beinhaltet ein <div>, das Text und ein Kontrollkästchen enthält.

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 fügt einen Listener zum wheel-Ereignis des Containers hinzu, das standardmäßig den Container scrollt. Der Listener führt eine langwierige Operation aus. Zunächst wird der Listener mit der passive-Option hinzugefügt, und immer wenn das Kontrollkästchen umgeschaltet wird, ändert der Code die passive-Option.

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

Die Wirkung ist, dass:

• Zunächst ist der Listener passiv, sodass das Versuchen, den Container mit dem Rad zu scrollen, sofort erfolgt.
• Wenn Sie "passive" deaktivieren und versuchen, den Container mit dem Rad zu scrollen, dann gibt es eine merkliche Verzögerung, bevor der Container scrollt, da der Browser warten muss, bis der langwierige Listener abgeschlossen ist.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• EventTarget.removeEventListener()
• Erstellung und Auslösen benutzerdefinierter Ereignisse
• Weitere Details zur Verwendung von this in Event-Handlern