CustomEvent

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

Aperçu de la méthode

void initCustomEvent(in DOMString type, in boolean canBubble, in boolean cancelable, in any detail);

Attributs

Attribut Type Description
detail any (type quelconque) Les données passées quand on initialise l'événement.

Méthodes

initCustomEvent()

Initialise l'évènement d'une manière similaire à la méthode éponyme dans les interfaces DOM Events.

void initCustomEvent(
  in DOMString type,
  in boolean canBubble,
  in boolean cancelable,
  in any detail
);

Paramètres

type
Le nom de l'évènement.
canBubble
Un booléen indiquant si l'événement se propage à travers le DOM ou non.
cancelable
Un booléen indiquant si l'événement peut être annulé.
detail
Les données passées quand on initialise un événement.

Constructeur

La spécification DOM4 a ajouté le support du constructeur CustomEvent.

CustomEvent(
  DOMString type,
  optional CustomEventInit eventInitDict
)

Paramètres

type
Le nom de l'évènement.
eventInitDict
Un objet qui fournit des propriétés de l'événement. Lisez la section CustomEventInit pour les détails.

CustomEventInit

bubbles
Un booléen indiquant si l'événement se propage à travers le DOM ou non (par défaut : false).
cancelable
Un booléen indiquant si l'évènement peut être annulé (par défaut : false).
detail
Les données passées quand on initialise un évènement.

Exemple d'utilisation de CustomEvent

// ajoute un écouteur d'événement approprié
obj.addEventListener("cat", function(e) { process(e.detail) });

// crée et déclenche l'événement
var event = new CustomEvent("cat", {"detail":{"hazcheeseburger":true}});
obj.dispatchEvent(event);

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support basique (Oui) 6 9 ? (Oui) (533.3)
Constructeur CustomEvent() 15 11 Pas de support 11.60 Nightly build (535.2)
Fonctionnalité Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Support basique ? ? ? ? ?

Notes pour Gecko

Cela est représenté par l'interface nsIDOMCustomEvent , qui étend l'interface nsIDOMEvent.

Poly-remplissage

Vous pouvez combler le manque de CustomEvent() dans Internet Explorer 9 et 10 avec le code suivant :

(function () {
  function CustomEvent ( event, params ) {
    params = params || { bubbles: false, cancelable: false, detail: undefined };
    var evt = document.createEvent( 'CustomEvent' );
    evt.initCustomEvent( event, params.bubbles, params.cancelable, params.detail );
    return evt;
   };

  CustomEvent.prototype = window.Event.prototype;

  window.CustomEvent = CustomEvent;
})();

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 q'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 document
 
function dispatchCustomEvent(doc) {

  // Cela ne fonctionnera pas. CustomEvent sera créé depuis la fenê  tre de Chrome et ne sera pas visible par le contenu.    
  // var myEvent = new CustomEvent("mytype");   
  // Créer le CustomEvent depuis la fenêtre du contenu 
  var myEvent = doc.defaultView.CustomEvent("mytype");   
  doc.dispatchEvent(myEvent);
}

L'attribut detail de votre CustomEvent sera sujet aux mêmes restrictions. Les valeurs de type String et Array seront lisibles par le contenu sans restrictions, mais pas les objets de type personalisé. Si vous utilisez ce genre d'objets, vous devrez définir les attributs de l'objet qui sont accessibles par le script en utilisant  __exposedProps__.

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

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

Voir aussi

Spécifications

Étiquettes et contributeurs liés au document

Contributeurs à cette page : Hell_Carlito, J.DMB, jbenoit, Porkepix, Lionel_Peramo
Dernière mise à jour par : Hell_Carlito,