Lesévénements DOM sont déclenchés pour notifier au code des « changements intéressants » qui peuvent affecter l'exécution du code. Ces changements peuvent résulter d'interactions avec l'utilisateur, comme l'utilisation de la souris ou le redimensionnement d'une fenêtre, de changements dans l'état de l'environnement sous-jacent (par exemple, une batterie faible ou des événements médiatiques provenant du système d'exploitation), et d'autres causes.

Chaque événement est représenté par un objet implémentant l'interfaceEvent, et peut avoir d'autres propriétés et/ou champs, permettant d'obtenir des informations supplémentaires au sujet de ce qui s'est produit. La documentation de chaque événement comporte un tableau (en haut de la page) qui comprend un lien vers l'interface de l'événement associé et d'autres informations pertinentes. Une liste complète des différents types d'événements est donnée dansEvent >ÉvénementInterfaces basées sur.

Cette rubrique fournit un index des principalessortes d'événements qui peuvent vous intéresser (animation, presse-papiers, workers, etc.) ainsi que les principales classes qui implémentent ces sortes d'événements. À la fin se trouve une liste exhaustive de tous les événements documentés.

Index des événements

Créer et déclencher des événements

En plus des événements déclenchés par les interfaces intégrées, vous pouvez créer et déclencher vous-même des événements DOM. Ces événements sont couramment appelésévénements synthétiques, par opposition aux événements déclenchés par le navigateur.

Créer des événements personnalisés

Les événements peuvent être créés avec le constructeurEvent comme suit :

const event = new Event("build");// Écouter l'événement.elem.addEventListener("build", (e) => {  /* … */});// Déclencher l'événement.elem.dispatchEvent(event);

Cet exemple utilise la méthodeEventTarget.dispatchEvent().

Ajouter des données personnalisées - CustomEvent()

Pour ajouter des données à l'objet événement, l'interfaceCustomEvent existe et la propriétédetail permet de transmettre des données personnalisées.Par exemple, l'événement peut être créé ainsi :

const event = new CustomEvent("build", { detail: elem.dataset.time });

Vous pourrez alors accéder à ces données supplémentaires dans l'écouteur d'événement :

function eventHandler(e) {  console.log(`L'heure est : ${e.detail}`);}

Ajouter des données personnalisées - sous-classer Event

L'interfaceEvent peut aussi être sous-classée. Cela est utile pour la réutilisation, pour des données personnalisées plus complexes, ou même pour ajouter des méthodes à l'événement.

class BuildEvent extends Event {  #buildTime;  constructor(buildTime) {    super("build");    this.#buildTime = buildTime;  }  get buildTime() {    return this.#buildTime;  }}

Ce code définit une classeBuildEvent avec une propriété en lecture seule et un type d'événement fixe.

L'événement peut alors être créé ainsi :

const event = new BuildEvent(elem.dataset.time);

Les données supplémentaires sont accessibles dans les écouteurs via les propriétés personnalisées :

function eventHandler(e) {  console.log(`L'heure est : ${e.buildTime}`);}

Propagation des événements (bubbling)

Il est souvent utile de déclencher un événement depuis un élément enfant et de le capter sur un ancêtre ; vous pouvez aussi transmettre des données avec l'événement :

<form>  <textarea></textarea></form>

const form = document.querySelector("form");const textarea = document.querySelector("textarea");// Créer un nouvel événement, autoriser la propagation, et transmettre des données via la propriété "detail"const eventAwesome = new CustomEvent("awesome", {  bubbles: true,  detail: { text: () => textarea.value },});// Le formulaire écoute l'événement personnalisé "awesome" et affiche la valeur transmiseform.addEventListener("awesome", (e) => console.log(e.detail.text()));// À chaque saisie, la textarea déclenche l'événement à partir d'elle-mêmetextarea.addEventListener("input", (e) => e.target.dispatchEvent(eventAwesome));

Créer et déclencher dynamiquement des événements

Les éléments peuvent écouter des événements qui n'ont pas encore été créés :

<form>  <textarea></textarea></form>

const form = document.querySelector("form");const textarea = document.querySelector("textarea");form.addEventListener("awesome", (e) => console.log(e.detail.text()));textarea.addEventListener("input", function () {  // Créer et déclencher un événement à la volée  // Remarque : on utilise ici une fonction classique pour que "this" représente l'élément  this.dispatchEvent(    new CustomEvent("awesome", {      bubbles: true,      detail: { text: () => textarea.value },    }),  );});

Déclencher des événements natifs

Cet exemple montre comment simuler un clic (c'est-à-dire générer un événement click par programmation) sur une case à cocher à l'aide des méthodes DOM.Voir l'exemple en action^(angl.).

function simulateClick() {  const event = new MouseEvent("click", {    view: window,    bubbles: true,    cancelable: true,  });  const cb = document.getElementById("checkbox");  const cancelled = !cb.dispatchEvent(event);  if (cancelled) {    // Un gestionnaire a appelé preventDefault.    alert("annulé");  } else {    // Aucun gestionnaire n'a appelé preventDefault.    alert("non annulé");  }}

Enregistrer des gestionnaires d'événements

Il existe deux méthodes recommandées pour enregistrer des gestionnaires. Le code du gestionnaire peut être exécuté lorsqu'un événement est déclenché soit en l'assignant à la propriétéonevent correspondante de l'élément cible, soit en enregistrant le gestionnaire comme écouteur à l'aide de la méthodeaddEventListener(). Dans les deux cas, le gestionnaire reçoit un objet conforme à l'interfaceEvent (ou à uneinterface dérivée). La principale différence est que plusieurs gestionnaires peuvent être ajoutés (ou supprimés) avec les méthodes d'écouteur d'événements.

Utiliser les propriétés onevent

Par convention, les objets JavaScript qui déclenchent des événements possèdent des propriétés "onevent" (nommées en préfixant "on" au nom de l'événement). Ces propriétés sont appelées pour exécuter le code du gestionnaire associé lorsque l'événement est déclenché, et peuvent aussi être appelées directement par votre code.

Pour définir le code du gestionnaire, il suffit de l'assigner à la propriété onevent appropriée. Un seul gestionnaire peut être assigné pour chaque événement sur un élément. Si besoin, le gestionnaire peut être remplacé en assignant une autre fonction à la même propriété.

L'exemple suivant montre comment définir une fonctiongreet() pour l'événementclick en utilisant la propriétéonclick.

const btn = document.querySelector("button");function greet(event) {  console.log("greet:", event);}btn.onclick = greet;

Notez qu'un objet représentant l'événement est passé comme premier argument au gestionnaire. Cet objet implémente ou dérive de l'interfaceEvent.

EventTarget.addEventListener

La façon la plus flexible de définir un gestionnaire d'événement sur un élément est d'utiliser la méthodeEventTarget.addEventListener. Cette approche permet d'assigner plusieurs écouteurs à un élément et de lessupprimer si besoin, à l'aide deEventTarget.removeEventListener.

L'exemple suivant montre comment une fonctiongreet() peut être définie comme écouteur/gestionnaire pour l'événementclick (vous pouvez utiliser une fonction anonyme si vous le souhaitez). Notez à nouveau que l'événement est passé comme premier argument au gestionnaire.

const btn = document.querySelector("button");function greet(event) {  console.log("greet:", event);}btn.addEventListener("click", greet);

La méthode peut aussi prendre des arguments/options supplémentaires pour contrôler la capture ou la suppression des événements. Plus d'informations sont disponibles sur la page de référence deEventTarget.addEventListener.

Utiliser AbortSignal

Une fonctionnalité notable des écouteurs d'événements est la possibilité d'utiliser un signal d'abandon pour supprimer plusieurs gestionnaires en même temps.

Cela se fait en passant le même objetAbortSignal à l'appel deaddEventListener() pour tous les gestionnaires que vous souhaitez pouvoir supprimer ensemble. Vous pouvez ensuite appelerabort() sur le contrôleur propriétaire du signal, ce qui supprimera tous les gestionnaires ajoutés avec ce signal. Par exemple, pour ajouter un gestionnaire que l'on pourra supprimer avec unAbortSignal :

const controller = new AbortController();btn.addEventListener(  "click",  (event) => {    console.log("greet:", event);  },  { signal: controller.signal },); // on passe un AbortSignal à ce gestionnaire

Ce gestionnaire peut ensuite être supprimé ainsi :

controller.abort(); // supprime tous les gestionnaires associés à ce contrôleur

Interaction de plusieurs gestionnaires d'événements

La propriété IDLonevent (par exemple,element.onclick = ...) et l'attribut HTMLonevent (par exemple,<button>) ciblent tous deux le même emplacement de gestionnaire unique. Le HTML est chargé avant que JavaScript puisse accéder au même élément, donc en général JavaScript remplace ce qui est spécifié dans le HTML. Les gestionnaires ajoutés avecaddEventListener() sont indépendants. Utiliseronevent ne supprime ni ne remplace les écouteurs ajoutés avecaddEventListener(), et inversement.

Lorsqu'un événement est déclenché, les écouteurs sont appelés en plusieurs phases. Il y a deux phases :capture etbulle (bubbling). En phase de capture, l'événement part de l'ancêtre le plus haut et descend l'arbre DOM jusqu'à la cible. En phase de bulle, l'événement remonte en sens inverse. Par défaut, les écouteurs écoutent en phase de bulle, mais ils peuvent écouter en phase de capture en passantcapture: true àaddEventListener(). Dans une même phase, les écouteurs sont appelés dans l'ordre où ils ont été enregistrés. Le gestionnaireonevent est enregistré la première fois qu'il devient non nul ; les réaffectations ultérieures ne changent que sa fonction de rappel, pas sa position dans l'ordre.

AppelerEvent.stopPropagation() empêche l'appel des écouteurs sur d'autres éléments plus loin dans la chaîne de propagation.Event.stopImmediatePropagation() empêche aussi l'appel des autres écouteurs sur le même élément.

Spécifications

Voir aussi

• Introduction aux événements
• Propagation des événements