type

Ein fallsensitiver String, der denEreignistyp darstellt, für den gehorcht werden soll.

listener

Das Objekt, das eine Benachrichtigung erhält (ein Objekt, das dasEvent-Interface implementiert), wenn ein Ereignis des spezifizierten Typs auftritt. Dies mussnull, ein Objekt mit einerhandleEvent()-Methode oder eine JavaScript-Funktion sein. SieheDer Ereignis-Listener-Callback für Details zum Callback selbst.

optionsOptional

Ein Objekt, das Merkmale über den Ereignis-Listener spezifiziert. Die verfügbarenOptionen sind:

captureOptional

Ein boolescher Wert, der angibt, dass Ereignisse dieses Typs an den registriertenlistener gesendet werden, bevor sie an ein darunterliegendesEventTarget im DOM-Baum gesendet werden. Wenn nicht angegeben, ist der Standardwertfalse.

onceOptional

Ein boolescher Wert, der angibt, dass derlistenerhöchstens einmal aufgerufen werden soll, nachdem er hinzugefügt wurde. Wenntrue, würde derlistener automatisch entfernt, wenn er aufgerufen wird. Wenn nicht angegeben, ist der Standardwertfalse.

passiveOptional

Ein boolescher Wert, der, wenntrue, angibt, dass die vonlistener angegebene Funktion niemalspreventDefault() aufrufen wird. Wenn ein passiver ListenerpreventDefault() aufruft, passiert nichts und es kann eine Warnung in der Konsole erzeugt werden.

Wenn diese Option nicht angegeben ist, ist der Standardwertfalse – außer dass in Browsern außer Safari der Standardwert fürwheel,mousewheel,touchstart undtouchmove-Ereignissetrue ist. SieheVerwendung passiver Listener, um mehr zu erfahren.

signalOptional

EinAbortSignal. Der Listener wird entfernt, wenn dieabort()-Methode desAbortController, der dasAbortSignal besitzt, aufgerufen wird. Wenn nicht spezifiziert, ist keinAbortSignal mit dem Listener verbunden.

useCaptureOptional

Ein boolescher Wert, der angibt, ob Ereignisse dieses Typs an denregistriertenlistenervor jedem darunterliegendenEventTarget im DOM-Baum gesendet werden, bevor es gesendet wird. Ereignisse, die den Baum durchlaufen, lösen keinen Listener aus, der zum Verwenden der Erfassung vorgesehen ist. Ereignis-Bubbling und -Erfassung sind zwei Arten der Ereignisverbreitung, die bei einem Element auftreten, das in einem anderen Element eingebettet ist, wenn beide Elemente eine Behandlung für dieses Ereignis registriert haben. Der Ereignisverbreitungsmodus bestimmt die Reihenfolge, in der Elemente das Ereignis empfangen. Siehedie DOM-Spezifikation undReihenfolge der JavaScript-Ereignisse für eine ausführliche Erklärung.Wenn nicht spezifiziert, ist der Standardwert füruseCapturefalse.

Hinweis:Für Ereignis-Listener, die am Ereignisziel angebracht sind, befindet sich das Ereignis in der Zielphase, nicht in den Erfassungs- und Bubble-Phasen.Listener in derErfassungsphase werden vor Listenern in der Ziel- und Bubble-Phase aufgerufen.

wantsUntrustedOptionalNicht standardisiert

Ein Firefox (Gecko)-spezifischer Parameter. Wenntrue, empfängt der Listenersynthetische Ereignisse, die von Webinhalten gesendet werden (der Standardwert istfalse fürBrowser-Chrome undtrue für reguläre Webseiten). DieserParameter ist nützlich für Code, der in Add-ons zu finden ist, sowie für den Browser selbst.

Keiner (undefined).

Der Ereignis-Listener kann entweder als Callback-Funktion oderals Objekt angegeben werden, dessenhandleEvent()-Methode als Callback-Funktion dient.

Die Callback-Funktion selbst hat dieselben Parameter und denselben Rückgabewert wie diehandleEvent()-Methode; das heißt, der Callback nimmt einen einzigen Parameter an: einObjekt basierend aufEvent, das das aufgetretene Ereignis beschreibt, und esgibt nichts zurück.

Ein Ereignishandler-Callback, der sowohlfullscreenchange als auchfullscreenerror behandeln kann, könnte so aussehen:

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

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

Wenn eine Handler-Funktion mitaddEventListener() an ein Element angehängt wird,ist der Wert vonthis innerhalb des Handlers eine Referenz aufdas Element. Es wird derselbe Wert wie der dercurrentTarget-Eigenschaft desEreignisarguments sein, das dem 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:Pfeilfunktionen haben ihren eigenenthis-Kontext nicht.

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

Wenn ein Ereignishandler (zum Beispielonclick) in der HTML-Quelle auf ein Element spezifiziert ist, wird der JavaScript-Code im Attributwert effektiv in einer Handler-Funktion umschlossen, die den Wert vonthis auf eine Weise bindet, die konsistent mitaddEventListener() ist; ein Vorkommen vonthis innerhalb des Codes repräsentiert eine Referenz auf das Element.

<table>  <!-- `this` refers to the table; logs 'my_table' -->  …</table>

Beachten Sie, dass der Wert vonthis innerhalb einer Funktion,aufgerufen durch den Codeim Attributwert, sich gemäßStandardregeln verhält. Dies wirdim folgenden Beispiel gezeigt:

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

Der Wert vonthis innerhalb vonlogID() ist eine Referenz auf das globaleObjektWindow (oderundefined im Falle vonstrict mode.

Spezifizieren von "this" mit bind()

Die MethodeFunction.prototype.bind() erlaubt es Ihnen, einen festenthis-Kontext für alle nachfolgenden Aufrufe festzulegen — Probleme zu umgehen, bei denen unklar ist, wasthis sein wird, abhängig vondem Kontext, aus dem Ihre Funktion aufgerufen wurde. Beachten Sie jedoch, dass Sie eineReferenz auf den Listener behalten müssen, damit Sie ihn später entfernen können.

Dies ist ein Beispiel mit und ohnebind():

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, false);    element.addEventListener("click", this.onclick2, false); // 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 verwendet eine spezielle Funktion namenshandleEvent(), umirgendein Ereignis abzufangen:

class Something {  name = "Something Good";  constructor(element) {    // Note that the listeners in this case are `this`, not this.handleEvent    element.addEventListener("click", this, false);    element.addEventListener("dblclick", this, false);  }  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, die Referenz aufthis zu handhaben, ist die Verwendung einer Pfeilfunktion, die keinen separatenthis-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();

Ereignis-Listener nehmen nur ein Argument an,einEvent oder eine Unterklasse vonEvent,die automatisch an den Listener übergeben wird, und der Rückgabewert wird ignoriert.Daher müssen Sie, um Daten in und aus einem Ereignis-Listener zu bekommen, anstatt die Daten durch Parameter und Rückgabewerte zu übergeben,Closures erstellen.

Die Funktionen, die als Ereignis-Listener übergeben werden, haben Zugriff auf alle Variablen, die in den äußeren Scopes 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 denFunktionen-Leitfaden für mehr Informationen über Funktions-Scopes.

const elems = document.getElementsByTagName("*");// Case 1for (const elem of elems) {  elem.addEventListener(    "click",    (e) => {      // Do something    },    false,  );}// Case 2function processEvent(e) {  // Do something}for (const elem of elems) {  elem.addEventListener("click", processEvent, false);}

Im obigen ersten Fall wird mit jederIteration der Schleife eine neue (anonyme) Handler-Funktion erstellt. Im zweiten Fall wird dieselbe zuvor deklarierte Funktion alsEreignis-Handler verwendet, was zu einem geringeren Speicherverbrauch führt, da nureine Handler-Funktion erstellt wird. Zudem ist im ersten Fall das Aufrufen vonremoveEventListener() nicht möglich, da keineReferenz auf die anonyme Funktion erhalten bleibt (oder hier, nicht zu einer dermehreren anonymen Funktionen, die die Schleife möglicherweise erstellt). Im zweiten Fall ist es möglich,myElement.removeEventListener("click", processEvent, false)auszuführen, daprocessEvent die Funktionsreferenz ist.

Eigentlich ist im Hinblick auf den Speicherverbrauch das Fehlen einer Funktionsreferenznicht das eigentliche Problem, sondern das Fehlen einerstatischen Funktionsreferenz.

Wenn ein Ereignis eine Standardaktion hat — beispielsweise einwheel-Ereignis, das standardmäßig den Container scrollt — kann der Browser im Allgemeinen die Standardaktion nicht starten, bis der Ereignis-Listener beendet ist, da er nicht im Voraus weiß, ob der Ereignis-Listener die Standardaktion durch Aufrufen vonEvent.preventDefault() abbrechen könnte. Wenn der Ereignis-Listener zu lange zur Ausführung braucht, kann dies zu einer merklichen Verzögerung führen, auch bekannt alsjank, bevor die Standardaktion ausgeführt werden kann.

Indem man diepassive-Option auftrue setzt, erklärt ein Ereignis-Listener, dass er die Standardaktion nicht abbrechen wird, sodass der Browser die Standardaktion sofort starten kann, ohne auf das Ende des Listeners zu warten. Ruft der Listener dannEvent.preventDefault() auf, hat dies keine Wirkung.

Die Spezifikation füraddEventListener() definiert den Standardwert für diepassive-Option als immerfalse. Um jedoch die Vorteile der Scrollleistung passiver Listener bei Legacy-Code zu nutzen, haben moderne Browser den Standardwert derpassive-Option für diewheel,mousewheel,touchstart undtouchmove-Ereignisse auf Dokument-Ebene-Elementen wieWindow,Document undDocument.body auftrue geändert. Dies verhindert, dass der Ereignis-Listenerdas Ereignis abbricht, sodass es das Rendern der Seite beim Scrollen des Benutzers nicht blockieren kann.

Aufgrund dessen müssen Sie, wenn Sie dieses Verhalten überschreiben und sicherstellen möchten, dass diepassive-Optionfalse ist, sie explizit auffalse setzen (anstatt sich auf den Standardwert zu verlassen).

Sie müssen sich keine Sorgen um den Wert vonpassive für das grundlegendescroll-Ereignis machen.Da es nicht abgebrochen werden kann, können Ereignis-Listener das Rendern der Seite sowieso nicht blockieren.

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

Dieses Beispiel demonstriert, wieaddEventListener() verwendet wird, um auf Mausklicks auf einem Element zu achten.

HTML

<table>  <tr>    <td>one</td>  </tr>  <tr>    <td>two</td>  </tr></table>

JavaScript

// Function to change the content of t2function modifyText() {  const t2 = document.getElementById("t2");  const isNodeThree = t2.firstChild.nodeValue === "three";  t2.firstChild.nodeValue = isNodeThree ? "two" : "three";}// Add event listener to tableconst el = document.getElementById("outside");el.addEventListener("click", modifyText, false);

In diesem Code istmodifyText() ein Listener fürclick-Ereignisse, die mitaddEventListener() registriert wurden. Ein Klick irgendwo in der Tabelle blubbert bis zum Handler hoch und führtmodifyText() aus.

Ergebnis

Dieses Beispiel demonstriert, wie man einaddEventListener() hinzufügt, das mit einemAbortSignal abgebrochen werden kann.

HTML

<table>  <tr>    <td>one</td>  </tr>  <tr>    <td>two</td>  </tr></table>

JavaScript

// Add an abortable event listener to tableconst controller = new AbortController();const el = document.getElementById("outside");el.addEventListener("click", modifyText, { signal: controller.signal });// Function to change the content of t2function 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 modifizieren wir den Code des vorherigen Beispiels so, dass, nachdem der Inhalt der zweiten Zeile auf "three" geändert wurde,abort() vomAbortController aufgerufen wird, den wir an denaddEventListener()-Aufruf übergeben haben. Das Ergebnis ist, dass der Wert dauerhaft "three" bleibt, da wir keinen Code mehr haben, der auf ein Klick-Ereignis hört.

Ergebnis

Hier schauen wir uns an, wie man eine anonyme Funktion verwendet, um Parameter an denEreignis-Listener zu übergeben.

HTML

<table>  <tr>    <td>one</td>  </tr>  <tr>    <td>two</td>  </tr></table>

JavaScript

// Function to change the content of t2function modifyText(newText) {  const t2 = document.getElementById("t2");  t2.firstChild.nodeValue = newText;}// Function to add event listener to tableconst el = document.getElementById("outside");el.addEventListener(  "click",  function () {    modifyText("four");  },  false,);

Beachten Sie, dass der Listener eine anonyme Funktion ist, die Code einkapselt, der dannwiederum in der Lage ist, Parameter an diemodifyText()-Funktion zu senden, welche für die eigentliche Reaktion auf das Ereignis verantwortlich ist.

Ergebnis

Dieses Beispiel demonstriert einen Ereignis-Listener, der mit einer Pfeilfunktionimplementiert ist.

HTML

<table>  <tr>    <td>one</td>  </tr>  <tr>    <td>two</td>  </tr></table>

JavaScript

// Function to change the content of t2function modifyText(newText) {  const t2 = document.getElementById("t2");  t2.firstChild.nodeValue = newText;}// Add event listener to table with an arrow functionconst el = document.getElementById("outside");el.addEventListener(  "click",  () => {    modifyText("four");  },  false,);

Ergebnis

Bitte beachten Sie, dass, während anonyme und Pfeilfunktionen ähnlich sind, sie unterschiedlichethis-Bindungen haben. Während anonyme (und alle traditionellen JavaScript-Funktionen)ihre eigenenthis-Bindungen erstellen, erben Pfeilfunktionen diethis-Bindung der umgebenden Funktion.

Das bedeutet, dass die Variablen und Konstanten, die der umgebenden Funktion verfügbar sind,auch dem Ereignishandler zur Verfügung stehen, wenn eine Pfeilfunktion verwendet wird.

HTML

<div>  outer, once & none-once  <div>    middle, capture & none-capture    <a href="https://www.mozilla.org">      inner1, passive & preventDefault(which is not allowed)    </a>    <a href="https://developer.mozilla.org/">      inner2, none-passive & preventDefault(not open new page)    </a>  </div></div><hr /><button>Clear logs</button><section></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: #ddd;  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 die äußeren, mittleren und inneren Container an, um zu sehen, wie die Optionen funktionieren.

Man kann mehr als eine der Optionen imoptions-Parameter setzen. Im folgenden Beispiel setzen wir zwei Optionen:

• passive, um zu bestätigen, dass der HandlerpreventDefault() nicht aufrufen wird
• once, um sicherzustellen, dass der Ereignis-Handler nur einmal aufgerufen wird.

HTML

<button>You have not clicked this button.</button><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 withconst initialText = buttonToBeClicked.textContent;// the text that the button contains after being clickedconst clickedText = "You have clicked this button.";// we hoist the event listener callback function// to prevent having duplicate listeners attachedfunction 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 againresetButton.addEventListener("click", () => {  buttonToBeClicked.textContent = initialText;  addListener();});addListener();

Ergebnis

Das folgende Beispiel zeigt den Effekt des Setzens vonpassive. Es beinhaltet ein<div>, das etwas Text enthält und ein Kontrollkästchen.

HTML

<div>  <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" 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 zumwheel-Ereignis des Containers hinzu, der standardmäßig den Container scrollt. Der Listener führt eine lang laufende Operation aus. Zunächst wird der Listener mit derpassive-Option hinzugefügt, und immer wenn das Kontrollkästchen umgeschaltet wird, schaltet der Code diepassive-Option um.

const passive = document.querySelector("#passive");passive.addEventListener("change", (event) => {  container.removeEventListener("wheel", wheelHandler);  container.addEventListener("wheel", wheelHandler, {    passive: passive.checked,    once: true,  });});const container = document.querySelector("#container");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

Der Effekt ist:

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

• EventTarget.removeEventListener()
• Erstellen und Auslösen benutzerdefinierter Ereignisse
• Mehr Details zur Verwendung vonthis in Ereignis-Handlern