Object.prototype.watch()

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.

Valeur de retour

undefined.

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

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

• Object.unwatch()
• Object.observe()