Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez également contribuer en rejoignant la communauté francophone sur MDN Web Docs.

Node.setUserData()

Obsolète

Cette fonctionnalité est obsolète. Bien qu'encore supportée par des navigateurs, son utilisation est découragée pour tout nouveau projet. Évitez de l'utiliser.

La méthode Node.setUserData() permet à un utilisateur de joindre (ou supprimer) des données à un élément, sans avoir besoin de modifier le DOM. Notez que ces données ne seront pas conservées lors de l'importation via Node.importNode, comme avec les opérations Node.cloneNode() et Node.renameNode() (bien que Node.adoptNode conserve l'information), et les tests d'égalité dans Node.isEqualNode() ne prennent pas en compte les données de l'utilisateur lors de l'évaluation.

Cette méthode offre l'avantage d'associer des données à des noeuds spécifiques sans nécessiter de modification de la structure du document et de façon standard, mais cela signifie aussi que des étapes supplémentaires peuvent être nécessaires si l'on souhaite sérialiser l'information ou l'inclure sur un clone, importer ou renommer des opérations.

Les méthodes Node.getUserData et Node.setUserData ne sont plus disponibles depuis le contenu Web. HTMLElement.dataset ou WeakMap peuvent être utilisées à la place.

Syntaxe

var prevUserData = someNode.setUserData(userKey, userData, handler);

Paramètres

  • userKey est utilisé comme une clé  par laquelle on peut ensuite obtenir les données stockées. Plus d'une clé peuvent être définies pour un nœud donné.
  • handler est un rappel qui sera appelé à chaque fois que le noeud est cloné, importé, renommé, supprimé ou adopté ; une fonction peut être utilisée ou un objet mettant en œuvre la méthode handle (partie de l'interface UserDataHandler (en-US)). Le gestionnaire recevra 5 arguments : un entier (integer) représentant le type d'opération (tel que 1 pour indiquer une opération de clonage), la clé utilisateur, les données sur le noeud, le noeud source (null s'il a été supprimé), le noeud de destination (le nouveau noeud créé ou null si aucun). Si aucun gestionnaire n'est souhaité, il faut spécifier null.
  • userData est l'objet à associer à userKey sur someNode. Si null, tout objet précédemment enregistré et l'UserDataHandler associé à userKey sur ce noeud seront supprimés.

Exemple

var d = document.implementation.createDocument('', 'test', null);
d.documentElement.setUserData('key', 15, {handle:function (o, k, d, s, ds) {console.log(o+'::'+k+'::'+d+'::'+s+'::'+ds)}}); // 2::key::15::[object Element]::[object Element]
console.log(d.documentElement.getUserData('key')); // 15
var e = document.importNode(d.documentElement, true); // provoque l'appel du gestionnaire
console.log(e.getUserData('key')); // null puisque les données utilisateur ne sont pas copiées.

Spécifications

Spécification Statut Commentaire
DOM
La définition de 'Node' dans cette spécification.		 Standard évolutif Supprimé de la  spécification.
Document Object Model (DOM) Level 3 Core Specification
La définition de 'Node.setUserData()' dans cette spécification.		 Obsolete Définition initiale.

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi