Object.prototype.watch()

Non standard
Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.

Attention : Si possible, ne pas utiliser watch() et unwatch(). En effet, ces deux méthodes ne sont implémentées qu'avec Gecko et ne sont prévues que pour du débogage. De plus, l'ajout de points d'arrêts conditionnels a de graves impacts sur les performances, notamment sur les objets globaux comme window. Il est conseillé d'utiliser les accesseurs et mutateurs ou les proxies. Voir le tableau de compatibilité ci-après pour plus de détails. Attention également à ne pas confondre Object.watch et Object.observe.

La méthode watch() permet d'appeler une fonction lorsqu'une propriété est affectée.

Syntaxe

obj.watch(prop, handler)

Paramètres

prop
Le nom d'une propriété d'un objet dont on souhaite surveiller les changements.
handler
Une fonction à appeler quand la valeur de la propriété est modifiée.

Description

Cette méthode permet de surveiller les assignations à une propriété appelée prop de l'objet courant, et appelle handler(prop, ancienneValeur, nouvelleValeur) dès que prop est définie et enregistre la valeur de retour dans cette propriété. Un tel point de surveillance peut filtrer (ou rendre null) l'assignation de la valeur, en renvoyant une valeur nouvelleValeur modifiée (ou en renvoyant ancienneValeur).

Si une propriété pour laquelle un point de surveillance avait été défini, celui-ci ne disparait pas. Si la propriété est recréée par la suite, le point de surveillance sera toujours en activité.

Pour retirer un point de surveillance, utilisez la méthode unwatch()/ Par défaut, la méthode watch est héritée par tous les objets descendant d'Object.

Le débogueur JavaScript a des fonctionnalités similaires à celles fournies par cette méthode, ainsi que d'autres options de débogage. Pour en savoir plus, voir le débogueur JavaScript.

Dans Firefox, handler n'est appelé que pour les assignations par script, pas depuis du code natif. Par exemple, window.watch('location', myHandler) n'appellera pas myHandler si l'utilisateur clique sur un lien vers une cible dans le document courant. Par contre, window.location += '#myAnchor' appellera myHandler :

Exemples

Utiliser watch et unwatch

var o = {p:1};
o.watch("p",
   function (id, oldval, newval) {
      console.log("o." + id + " a été modifiée de " + oldval + " en " + newval);
      return newval;
   });

o.p = 2;
o.p = 3;
delete o.p;
o.p = 4;

o.unwatch('p');
o.p = 5;

Ce script affiche la sortie suivante :

o.p a été modifiée de 1 en 2
o.p a été modifiée de 2 en 3
o.p a été modifiée de undefined en 4

Utiliser watch pour valider les propriétés d'un objet

La méthode watch peut être utilisée pour tester les assignations d'une propriété d'objet. Cet exemple s'assure que toute Personne a un nom valide et un age entre 0 et 200.

Personne = function(name,age) {
  this.watch("age", Personne.prototype._isValidAssignment);
  this.watch("nom", Personne.prototype._isValidAssignment);
  this.nom = nom;
  this.age = age;
}

Personne.prototype.toString = function() {
  return this.nom + ", " + this.age;
};

Personne.prototype._isValidAssignment = function(id, oldval, newval) {
  if (id == "nom" && (!newval || newval.length > 30)) {
    throw new RangeError("nom invalide pour " + this);
  }
  if (id == "age"  && (newval < 0 || newval > 200)) {
    throw new RangeError("âge invalide pour " + this);
  }
  return newval;
}

will = new Personne("Will", 29);
console.log(will);   // Will, 29

try {
  will.nom = "";
} catch (e) {
  console.log(e);
}

try {
  will.age = -4;
} catch (e) {
  console.log(e);
}

Ce script affichera la sortie suivante :

Will, 29
RangeError: nom invalide pour Will, 29
RangeError: âge invalide pour Will, 29

Spécifications

Cette méthode ne fait partie d'aucune spécification. Elle a été implémentée avec JavaScript 1.2.

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support simple Pas de support (Oui) Pas de support Pas de support Pas de support
Fonctionnalité Android Chrome pour Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support simple Pas de support Pas de support (Oui) Pas de support Pas de support Pas de support

Notes de compatibilité

  • Cette prothèse d'émulation (polyfill) permet d'utiliser watch dans les différents navigateurs compatibles avec ES5
  • Utiliser un objet Proxy permet d'avoir accès à plus d'informations, de façon plus profonde sur la manière dont les propriétés sont changées.
  • Appeler watch() sur un objet Document renvoyait une exception TypeError depuis Firefox 23 (bug 903332). Cette régression a été résolue avec Firefox 27.

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, teoli, Jeremie, BenoitL
 Dernière mise à jour par : SphinxKnight,