CustomEvent

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

Aperçu de la méthode

Attributs

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

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

• Interaction entre pages privilégiées et non-privilégiées
• Window.postMessage

Spécifications

• DOM4 : Interface CustomEventED
• DOM Level 3 Events : CustomEventWD