CKTIS / JavaScript
MutationRecord : lire une modification du DOM
Identifiez le type de modification et le nœud concerné, examinez les enfants ajoutés ou retirés et déterminez quand l’enregistrement contient l’ancienne valeur.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
const { type, target, addedNodes, removedNodes, attributeName, oldValue } = record;Un MutationRecord décrit une modification du DOM. Un MutationObserver transmet les enregistrements à sa fonction de rappel dans une microtâche, et non pendant la modification elle-même. Ces propriétés sont en lecture seule. Lisez d’abord type pour interpréter les autres champs. Cette API fait partie de la plateforme web, pas d’ECMAScript 2024 : ne supposez pas qu’elle est disponible dans un environnement sans DOM.
Pour type === "childList", target est le nœud dont les enfants directs ont changé. addedNodes et removedNodes sont des objets NodeList qui contiennent respectivement les enfants ajoutés et retirés lors de cette modification. Si aucun enfant n’a été ajouté ou retiré, la liste correspondante est vide, et non null. Déplacer un nœud peut produire deux enregistrements distincts, l’un pour le retrait et l’autre pour l’ajout.
Pour type === "attributes", target est l’élément modifié. attributeName est le nom local de l’attribut, sans préfixe d’espace de noms. oldValue contient l’ancienne valeur de l’attribut sous forme de chaîne si observe() a reçu l’option attributeOldValue: true. Sinon, oldValue vaut null, tout comme lorsque l’attribut n’existait pas auparavant.
Pour type === "characterData", target est le nœud CharacterData lui-même, par exemple un nœud texte, et non son parent. oldValue contient les anciennes données sous forme de chaîne uniquement avec characterDataOldValue: true ; sinon, la propriété vaut null. Pour "childList", oldValue vaut toujours null. Hors du cas "attributes", attributeName vaut null, et hors du cas "childList", les deux listes de nœuds sont vides.
Avec subtree: true, le target de l’enregistrement peut être un descendant du nœud passé à observe(). Il n’y a pas de champ newValue : lire les données de target donne l’état actuel, qui peut déjà refléter des modifications ultérieures.
Exemples
<!doctype html>
<meta charset="utf-8">
<title>MutationRecord example</title>
<script>
(() => {
const root = document.createElement("div");
const text = document.createTextNode("hello");
const child = document.createElement("span");
root.setAttribute("data-state", "before");
root.append(text);
const observer = new MutationObserver(() => {});
observer.observe(root, {
attributes: true,
attributeOldValue: true,
characterData: true,
characterDataOldValue: true,
childList: true,
subtree: true,
});
root.setAttribute("data-state", "after");
text.data = "world";
root.append(child);
child.remove();
const records = observer.takeRecords();
observer.disconnect();
const nodeNames = (nodes) => Array.from(nodes, (node) => node.nodeName);
for (const { type, target, addedNodes, removedNodes, attributeName, oldValue } of records) {
console.log(JSON.stringify([
type, target.nodeName, nodeNames(addedNodes), nodeNames(removedNodes),
attributeName, oldValue,
]));
}
})();
</script>Résultat
["attributes","DIV",[],[],"data-state","before"] ["characterData","#text",[],[],null,"hello"] ["childList","DIV",["SPAN"],[],null,null] ["childList","DIV",[],["SPAN"],null,null]
Enregistrez l’exemple complet dans un fichier HTML, ouvrez-le dans un navigateur et consultez la sortie dans la console. `takeRecords()` récupère les enregistrements et vide la file avant l’appel de la fonction de rappel : le code affiche donc quatre enregistrements dans l’ordre. L’enregistrement d’ajout contient toujours `SPAN`, même si le nœud a ensuite été retiré.
Leçons associées
- JavaScript · Leçon 31 · Intermédiaire · Version : 3
Sources
- MutationRecord
- MutationRecord: target property
- MutationRecord: addedNodes property
- MutationRecord: removedNodes property
- MutationRecord: attributeName property
- MutationRecord: oldValue property
- MutationObserver: observe() method
- MutationObserver: takeRecords() method
- Using microtasks in JavaScript with queueMicrotask()