Événements DOM
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'interface Event, 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 dans Event >Événement Interfaces basées sur.
Cette rubrique fournit un index des principales sortes 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
| Type d'événement | Description | Documentation |
|---|---|---|
| Animation |
Les événements liés à l'API Web Animation API. Utilisé pour répondre aux changements d'état de l'animation (par exemple, lorsqu'une animation commence ou se termine). |
Événements d'animation déclenchés sur
Document,
Window,
HTMLElement.
|
| Récupération asynchrone des données | Événements liés à l'extraction des données. |
Événements déclenchés sur
AbortSignal,
XMLHttpRequest,
FileReader.
|
| Presse-papiers |
Les événements liés à l'API Clipboard API. Utilisé pour notifier lorsque le contenu est coupé, copié ou collé. |
Événements déclenchés sur
Document,
Element,
Window.
|
| Composition |
Événements liés à la composition ; saisie "indirecte" du texte (au lieu d'utiliser les touches normales du clavier). Par exemple, un texte saisi via un moteur de conversion de la parole en texte, ou l'utilisation de combinaisons de touches spéciales qui modifient les pressions sur le clavier pour représenter de nouveaux caractères dans une autre langue. |
Événements déclenchés sur
Element.
|
| Transition CSS |
Événements liés aux Transitions CSS. Fournit des événements de notification lorsque les transitions CSS commencent, s'arrêtent, sont annulées, etc. |
Événements déclenchés sur
Document,
HTMLElement,
Window.
|
| Base de données |
Événements liés aux opérations de la base de données : ouverture, fermeture, transactions, erreurs, etc. |
Événements déclenchés sur
IDBDatabase,
IDBOpenDBRequest,
IDBRequest,
IDBTransaction.
|
| Mutation du DOM |
Événements liés aux modifications de la hiérarchie et des nœuds du Document Object Model (DOM). |
Avertissement : Mutation Events sont dépréciés. L'API Mutation Observers doit être utilisé à la place. |
| Glisser/Déposer, Roue |
Les événements liés à l'utilisation de l'API Glisser/Déposer et WheelEvent. Les événements Glisser/Déposer et Roue sont dérivés des événements de la souris. Bien qu'ils soient déclenchés lors de l'utilisation de la molette de la souris ou du glisser/déposer, ils peuvent également être utilisés avec d'autres matériels appropriés. |
Les événements de Glisser/Déposer déclenchés sur
Les événements de la Roue déclenchés sur
|
| Ciblage |
Les événements liés aux éléments qui gagnent et perdent la sélection. |
Événements déclenchés sur
Element, Window.
|
| Formulaire |
Événements liés à la construction, la réinitialisation et la soumission de formulaires. |
Événements déclenchés sur
HTMLFormElement.
|
| Plein écran |
Evénements relatifs à l'API Fullscreen API. Utilisé pour notifier la transition entre le mode plein écran et le mode fenêtré, ainsi que les erreurs survenant pendant cette transition. |
Événements déclenchés sur
Document,
Element.
|
| Manette de jeu |
Evénements relatifs à l'API Gamepad API. |
Événements déclenchés sur
Window.
|
| Gestes |
Les événements tactiles sont recommandés pour la mise en œuvre des gestes. |
Événements déclenchés sur
En outre, il existe un certain nombre d'événements de geste non standard :
|
| Historique |
Les événements liés à l'API de Manipulation de l'historique du navigateur. |
Événements déclenchés sur
Window.
|
| Gestion de l'affichage du contenu des éléments HTML |
Événements liés à la modification de l'état d'un élément d'affichage ou textuel. |
Événements déclenchés sur
HTMLDetailsElement,
HTMLDialogElement,
HTMLSlotElement.
|
| Entrées |
Événements liés aux éléments d'entrée HTML, par ex.
|
Événements déclenchés sur
HTMLElement,
HTMLInputElement.
|
| Clavier |
Événements liés à l'utilisation d'un clavier. Utilisé pour notifier lorsque les touches sont déplacées vers le haut, vers le bas, ou simplement pressées. |
Événements déclenchés sur
Document,
Element.
|
| Manifeste |
Événements liés à l'installation de Manifeste des applications web. |
Événements déclenchés sur
Window.
|
| Médias |
Événements liés à l'utilisation des médias (y compris l'API de capture et de diffusion de médias, Web Audio API, Picture-in-Picture API, etc.). |
Événements déclenchés sur
ScriptProcessorNode,
HTMLMediaElement,
AudioTrackList,
AudioScheduledSourceNode,
MediaRecorder,
MediaStream,
MediaStreamTrack,
VideoTrackList,
HTMLTrackElement,
OfflineAudioContext, TextTrack,
TextTrackList, Element/audio,
Element/video.
|
| Messagerie |
Événements liés à la réception par une fenêtre d'un message provenant d'un autre contexte de navigation. |
Événements déclenchés sur
Window.
|
| Souris |
Événements liés à l'utilisation d'une souris d'ordinateur. Utilisé pour notifier le clic de la souris, le double-clic, les événements haut et bas, le clic droit, le déplacement dans et hors d'un élément, la sélection de texte, etc. Les événements de type pointeur constituent une alternative aux événements de type souris, indépendamment du matériel utilisé. Les événements de type "glisser" et "roue" sont dérivés des événements de type "souris". |
Les événements de souris déclenchés sur
Element
|
| Réseau/Connexion |
Événements liés à l'obtention et à la perte d'une connexion réseau. |
Événements déclenchés sur
Événements déclenchés sur
|
| Paiements |
Les événements liés à l'API Payment Request API. |
Événements déclenchés sur
|
| Performance |
Événements liés aux APIs Performance API. |
Événements déclenchés sur
|
| Pointeur |
Les événements liés à l'API Pointer Events API. Fournit une notification agnostique du matériel à partir des dispositifs de pointage, y compris la souris, la souris tactile, le stylo/stylet. |
Événements déclenchés sur
Document,
HTMLElement.
|
| Impression | Événements liés à l'impression. |
Événements déclenchés sur
Window.
|
| Rejet de promesse |
Événements envoyés au contexte global du script lorsqu'une promesse JavaScript est rejetée. |
Événements déclenchés sur
Window.
|
| Sockets |
Les événements liés à l'API WebSockets API. |
Événements déclenchés sur
Websocket.
|
| SVG | Événements liés aux images SVG. |
Événements déclenchés sur
|
| Sélection de texte |
Événements liés à la sélection du texte. |
Événements déclenchés sur
|
| Tactile |
Les événements liés à l'API Événements tactiles. Fournit des événements de notification provenant de l'interaction avec un écran tactile (c'est-à-dire l'utilisation d'un doigt ou d'un stylet). Non lié à l'API Force Touch API. |
Événements déclenchés sur
Document,
Element.
|
| Réalité virtuelle |
Les événements liés à l'API WebXR Device API. |
Événements déclenchés sur
XRSystem, XRSession,
XRReferenceSpace.
|
| RTC (communication en temps réel) |
Les événements liés à l'API WebRTC API. |
Événements déclenchés sur
RTCDataChannel,
RTCDTMFSender,
RTCIceTransport,
RTCPeerConnection.
|
| Événements envoyés par le serveur |
Les événements liés à l'API des événements envoyés par le serveur. |
Événements déclenchés sur
EventSource.
|
| Synthèse vocale |
Les événements liés à l'API Web Speech API. |
Événements déclenchés sur
SpeechSynthesisUtterance.
|
| Workers |
Les événements liés aux APIs Web Workers API, Service Worker API, Broadcast Channel API, et Channel Messaging API. Utilisé pour répondre aux nouveaux messages et aux erreurs d'envoi de messages. Les travailleurs de service peuvent également être notifiés d'autres événements, notamment les notifications push, les utilisateurs qui cliquent sur les notifications affichées, le fait que l'abonnement push a été invalidé, la suppression d'éléments de l'index de contenu, etc. |
Événements déclenchés sur
ServiceWorkerGlobalScope,
DedicatedWorkerGlobalScope,
SharedWorkerGlobalScope,
WorkerGlobalScope, Worker,
WorkerGlobalScope,
BroadcastChannel,
MessagePort.
|
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 constructeur Event 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éthode EventTarget.dispatchEvent().
Ajouter des données personnalisées - CustomEvent()
Pour ajouter des données à l'objet événement, l'interface CustomEvent 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'interface Event 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 classe BuildEvent 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 transmise
form.addEventListener("awesome", (e) => console.log(e.detail.text()));
// À chaque saisie, la textarea déclenche l'événement à partir d'elle-même
textarea.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éthode addEventListener(). Dans les deux cas, le gestionnaire reçoit un objet conforme à l'interface Event (ou à une interface 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.
Attention : Une troisième méthode, qui consiste à utiliser les attributs HTML onevent, n'est pas recommandée ! Ils alourdissent le balisage, le rendent moins lisible et plus difficile à déboguer. Pour plus d'informations, voir Gestionnaires d'événements en ligne.
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 fonction greet() pour l'événement click 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'interface Event.
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éthode EventTarget.addEventListener. Cette approche permet d'assigner plusieurs écouteurs à un élément et de les supprimer si besoin, à l'aide de EventTarget.removeEventListener.
Note : La possibilité d'ajouter et de supprimer des gestionnaires permet, par exemple, d'utiliser le même bouton pour différentes actions selon le contexte. De plus, dans des programmes plus complexes, nettoyer les anciens gestionnaires inutilisés peut améliorer l'efficacité.
L'exemple suivant montre comment une fonction greet() peut être définie comme écouteur/gestionnaire pour l'événement click (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 de EventTarget.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 objet AbortSignal à l'appel de addEventListener() pour tous les gestionnaires que vous souhaitez pouvoir supprimer ensemble. Vous pouvez ensuite appeler abort() 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 un AbortSignal :
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é IDL onevent (par exemple, element.onclick = ...) et l'attribut HTML onevent (par exemple, <button onclick="...">) 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 avec addEventListener() sont indépendants. Utiliser onevent ne supprime ni ne remplace les écouteurs ajoutés avec addEventListener(), et inversement.
Lorsqu'un événement est déclenché, les écouteurs sont appelés en plusieurs phases. Il y a deux phases : capture et bulle (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 passant capture: true à addEventListener(). Dans une même phase, les écouteurs sont appelés dans l'ordre où ils ont été enregistrés. Le gestionnaire onevent 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.
Appeler Event.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
| Specification |
|---|
| DOM # events |
| HTML # events-2 |