CKTIS / JavaScript
MutationRecord — un enregistrement de modification du DOM
MutationRecord décrit une seule modification du DOM observée. Découvrez comment en identifier le type et le nœud concerné, examiner les nœuds ajoutés et supprimés, et récupérer le nom d’un attribut ainsi que sa valeur précédente.
Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
record.type; record.target; record.addedNodes; record.removedNodes; record.attributeName; record.oldValueMutationRecord est une interface en lecture seule qui décrit une modification du DOM observée par un MutationObserver. Les enregistrements sont transmis dans le tableau passé à la fonction de rappel de l’observateur ; les enregistrements en attente peuvent aussi être récupérés avec takeRecords(). Il s’agit d’une API du DOM, et non d’une partie d’ECMAScript. MDN la classe comme largement disponible dans les navigateurs depuis juillet 2015 ; la présence de Node 24 dans un projet ne prouve pas la prise en charge de cette API de navigateur.
MutationRecord.type vaut "attributes", "characterData" ou "childList". MutationRecord.target désigne respectivement l’élément dont l’attribut a changé, le nœud CharacterData modifié ou le nœud dont la liste d’enfants a changé — et non l’enfant ajouté ou supprimé.
MutationRecord.addedNodes et MutationRecord.removedNodes sont des objets NodeList contenant les nœuds ajoutés et supprimés lors de cette modification. Chaque liste est vide en l’absence de nœuds correspondants. MutationRecord.attributeName contient le nom de l’attribut modifié pour "attributes" et vaut null pour les autres types.
MutationRecord.oldValue contient la valeur précédente de l’attribut uniquement si attributeOldValue est activé, ou les données CharacterData précédentes uniquement si characterDataOldValue est activé. Le type de mutation correspondant doit également être observé. Sinon, y compris pour "childList", la valeur est null ; un attribut auparavant absent peut aussi avoir une ancienne valeur null.
L’exemple observe un élément détaché et lit les enregistrements de manière synchrone avec takeRecords(), qui vide la file d’attente. Il n’est donc pas nécessaire d’attendre la fonction de rappel. Après avoir récupéré les enregistrements, il déconnecte l’observateur.
Exemples
(() => {
const root = document.createElement("div");
root.setAttribute("data-state", "idle");
const observer = new MutationObserver(() => {});
observer.observe(root, {
attributes: true,
attributeOldValue: true,
childList: true
});
root.setAttribute("data-state", "ready");
const child = document.createElement("span");
root.appendChild(child);
root.removeChild(child);
const records = observer.takeRecords();
observer.disconnect();
for (const record of records) {
console.log(JSON.stringify([
record.type,
record.target === root,
record.addedNodes.length,
record.removedNodes.length,
record.attributeName,
record.oldValue
]));
}
})();Résultat
["attributes",true,0,0,"data-state","idle"] ["childList",true,1,0,null,null] ["childList",true,0,1,null,null]
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.