CustomEvent

Les interfaces CustomEvent DOM sont des évènements initialisés par une application pour n'importe quel usage.

Note: Cette fonctionnalité est disponible via les Web Workers

Constructeur

CustomEvent() (en-US)

Crée un CustomEvent.

Propriétés

CustomEvent.detail Lecture seule

Toute donnée transmise lors de l'initialisation de l'événement.

Cette interface hérite des propriétés de son parent Event:

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)

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 Lecture seule

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

Event.originalTarget Lecture seule

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

Event.returnValue

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

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

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

CustomEvent.initCustomEvent()

Initialise un objet CustomEvent. Si l'événement a déjà été distribué, cette méthode ne fait rien.

Cette interface hérite les méthodes de son parent Event:

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

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

Spécification Statut Commentaire
DOM
La définition de 'CustomEvent' dans cette spécification.
Standard évolutif Définition initial

Compatibilité des navigateurs

BCD tables only load in the browser

Déclenchement à partir de code privilégié vers du code non-privilégié

Lors du déclenchement d'un CustomEvent depuis du code privilégié (une extension, par exemple) vers du code non-privilégié (une page web par exemple), vous devez prendre en considération la sécurité. Firefox et les autres applications Gecko empêchent qu'un objet créé dans un contexte soit utilisé dans un autre, ce qui empêchera généralement les failles de sécurité, mais ces restrictions peuvent aussi empêcher votre code de s'executer comme prévu.

Lors de la création d'un objet CustomEvent, vous devez créer l'objet à partir de la même fenêtre que celle où vous déclencherez l'évenement.

// doc est une référence au contenu du document
function dispatchCustomEvent(doc) {
  var eventDetail = Components.utils.cloneInto({foo: 'bar'}, doc.defaultView);
  var myEvent = doc.defaultView.CustomEvent("mytype", eventDetail);
  doc.dispatchEvent(myEvent);
}

Notez qu'exposer une fonction permettra au script de l'exécuter avec les privilèges qu'accorde Chrome ce qui peut ouvrir une faille de sécurité.

Voir aussi