Event
=====

L'interface **`Event`** interface représente un évènement qui se produit dans le DOM.

Un évènement peut être déclenché par une action humaine (clic avec la souris, appui sur une touche du clavier) ou généré par des API pour représenter la progression d'une tâche asynchrone. Il est également possible de déclencher un évènement à partir d'un programme, en appelant par exemple la méthode `HTMLElement.click()` sur un élément ou en définissant l'évènement avant de l'envoyer sur une cible avec la méthode `EventTarget.dispatchEvent()`.

Il existe de nombreux types d'évènements dont certains utilisent d'autres interfaces basées sur `Event`. L'interface `Event` contient les propriétés et méthodes qui sont communes à l'ensemble des évènements.

De nombreux éléments DOM peuvent être paramétrés afin d'accepter (« d'écouter ») ces évènements et d'exécuter du code en réaction afin de les traiter (« gérer »). Les gestionnaires d'évènements sont généralement connectés (« attachés ») aux éléments HTML (tels que `<button>`, `<div>`, `<span>`, etc.) grâce à la méthode `EventTarget.addEventListener()` qui remplace les anciens attributs de gestion d'évènement qui étaient auparavant utilisés en HTML. Avec cette méthode d'ajout plus récente, les gestionnaires peuvent également être déconnectés/détachés si besoin via la méthode `EventTarget.removeEventListener()`.

**Note :** Il est tout à fait possible d'attacher plusieurs gestionnaires d'évènement à un seul élément, y compris pour la gestion d'un évènement particulier. Ainsi, des modules de code indépendant peuvent attacher leurs gestionnaires de façon indépendante (par exemple, sur une page web, un module de publicité et un autre module d'analyse pourront tout à fait attacher des gestionnaires pour étudier la consultation d'une vidéo).

Lorsqu'il y a de nombreux éléments imbriqués, chacun ayant ses propres gestionnaires d'évènement, le traitement des évènements peut se révéler compliqué, notamment lorsqu'un élément parent reçoit le même évènement que ses éléments enfants (par exemple pour des évènements qui se déclenchent sur la surface visuelle de l'élément enfant). Dans ce cas, l'ordre du traitement de ces évènements dépend des paramètres de bouillonnement (*bubbling*) et de capture définis sur chaque gestionnaire ainsi déclenché.

Interfaces basées sur Event
---------------------------

Voici une liste des interfaces basées sur `Event` avec un lien vers leur documentation dans la référence MDN.

On notera que l'ensemble des interfaces d'évènements ont un nom qui termine par *Event* (« évènement » en anglais).

* `AnimationEvent`
* `AudioProcessingEvent`
* `BeforeInputEvent`
* `BeforeUnloadEvent`
* `BlobEvent`
* `ClipboardEvent` (en-US)
* `CloseEvent`
* `CompositionEvent`
* `CSSFontFaceLoadEvent`
* `CustomEvent`
* `DeviceMotionEvent`
* `DeviceOrientationEvent`
* `DeviceProximityEvent`
* `DOMTransactionEvent`
* `DragEvent` (en-US)
* `EditingBeforeInputEvent`
* `ErrorEvent`
* `FetchEvent`
* `FocusEvent`
* `GamepadEvent` (en-US)
* `HashChangeEvent` (en-US)
* `IDBVersionChangeEvent` (en-US)
* `InputEvent`
* `KeyboardEvent`
* `MediaStreamEvent`
* `MessageEvent`
* `MouseEvent`
* `MutationEvent` (en-US)
* `OfflineAudioCompletionEvent` (en-US)
* `OverconstrainedError` (en-US)
* `PageTransitionEvent`
* `PaymentRequestUpdateEvent` (en-US)
* `PointerEvent`
* `PopStateEvent` (en-US)
* `ProgressEvent` (en-US)
* `RelatedEvent`
* `RTCDataChannelEvent` (en-US)
* `RTCPeerConnectionIceEvent` (en-US)
* `SensorEvent`
* `StorageEvent` (en-US)
* `SVGEvent` (en-US)
* `SVGZoomEvent`
* `TimeEvent` (en-US)
* `TouchEvent` (en-US)
* `TrackEvent` (en-US)
* `TransitionEvent`
* `UIEvent`
* `UserProximityEvent`
* `WebGLContextEvent` (en-US)
* `WheelEvent`
Constructeur
------------

`Event()`

Crée un objet `Event` et le renvoie à l'appelant.

Propriétés
----------

`Event.bubbles` Lecture seule 

Un booléen qui indique si l'évènement bouillonne/remonte vers le haut dans l'arbre du DOM.

`Event.cancelBubble`

Un alias historique de `Event.stopPropagation()`. Définir sa valeur à `true` avant le retour d'un gestionnaire d'évènement empêchera la propagation de l'évènement.

`Event.cancelable` Lecture seule 

Un booléen qui indique si l'évènement peut être annulé.

`Event.composed` (en-US) Lecture seule 

Un booléen qui indique si l'évènement peut bouillonner entre l'arbre du shadow DOM et le DOM standard.

`Event.currentTarget` Lecture seule 

Une référence vers la cible actuellement enregistrée pour l'évènement. Il s'agit de l'objet vers lequel l'évènement est présentement destiné à être envoyé. Cette cible peut avoir été modifiée pendant la vie de l'évènement via un reciblage.

`Event.deepPath` (en-US) 
Non-standard

Un tableau (`Array`) de nœuds (`Node`) du DOM qui ont été parcourus lors du bouillonnement/de la remontée de l'évènement.

`Event.defaultPrevented` Lecture seule 

Indique si un appel à `Event.preventDefault()` a annulé l'évènement.

`Event.eventPhase` Lecture seule 

Indique la phase du flux de l'évènement qui est en cours de traitement.

`Event.explicitOriginalTarget` 
Non-standard
 Lecture seule 

La cible explicite et originnelle de l'évènement (spécifique à Mozilla).

`Event.originalTarget` 
Non-standard
 Lecture seule 

La cible originale de l'évènement avant tout reciblage (spécifique à Mozilla).

`Event.returnValue` 
Obsolète

Une propriété historique, introduite par Internet Explorer puis adoptée au sein de la spécification du DOM pour la compatibilité des sites existants. À la place, on privilégiera l'usage de `Event.preventDefault()` et `Event.defaultPrevented`.

`Event.srcElement` 
Non-standard

Un alias non-standard (provenant d'anciennes versions d'Internet Explorer) pour `Event.target`. Certains navigateurs le prennent en charge à des fins de compatibilité web.

`Event.target` Lecture seule 

Une référence à la cible à laquelle l'évènement était initialement destiné.

`Event.timeStamp` Lecture seule 

Le temps auquel l'évènement a été créé (exprimé en millisecondes). La spécification indique que cette valeur est relative à l'epoch mais l'implémentation des navigateurs peut varier. Des travaux sont en cours afin que cette valeur devienne une valeur de type `DOMHighResTimeStamp`.

`Event.type` Lecture seule 

Le nom de l'évènement, exprimé de façon insensible à la casse.

`Event.isTrusted` Lecture seule 

Indique si l'évènement a été initié par le navigateur (suite à une action humaine comme un clic) ou par un script (en utilisant une méthode de création comme `Event.initEvent`).

### Propriétés dépréciées

`Event.scoped` (en-US) Lecture seule  
Obsolète

Un booléen qui indique si l'évènement courant remontera de l'arbre du shadow DOM vers l'arbre du DOM classique. `Event.composed` (en-US) doit être utilisé à la place.

Méthodes
--------

`Event.composedPath()` (en-US)

Renvoie le chemin de l'évènement (c'est-à-dire les objets pour lesquels des gestionnaires d'évènements seront appelés). Ce chemin n'inclut pas les nœuds des arbres shadow si la racine shadow a été créée avec un `ShadowRoot.mode`.

`Event.preventDefault()`

Annule l'évènement (si celui-ci peut être annulé).

`Event.stopImmediatePropagation`

Pour l'évènement courant, empêche les autres gestionnaires d'évènements d'être appelés. Cela inclut les gestionnaires attachés au même élément ainsi que ceux attachés aux éléments qui seront parcourus ensuite (pendant la phase de capture par exemple).

`Event.stopPropagation`

Arrête la propagation des évènements plus loin dans le DOM.

### Méthodes dépréciées

`Event.initEvent()` 
Obsolète

Initialise la valeur d'un évènement créé. Si l'évènement a déjà diffusé, cette méthode n'a aucun effet.

Spécifications
--------------

| Specification |
| --- |
| DOM Standard # interface-event |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Les types d'évènement disponibles : Référence des évènements
* Comparaison des cibles d'évènements (`target` vs `currentTarget` vs `relatedTarget` vs `originalTarget`)
* Créer et déclencher des évènements personnalisés