Node.setUserData()

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.

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). 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

Compatibilité des navigateurs

[1] La méthode reste disponible dans les scripts chrome.

Voir aussi

• Node.getUserData()
• UserDataHandler
• DOMUserData