CKTIS / JavaScript
MutationRecord — un record di modifica del DOM
MutationRecord descrive una singola modifica del DOM osservata. Scopri come identificarne il tipo e il nodo interessato, esaminare i nodi aggiunti e rimossi e recuperare il nome di un attributo e il suo valore precedente.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
record.type; record.target; record.addedNodes; record.removedNodes; record.attributeName; record.oldValueMutationRecord è un’interfaccia di sola lettura che descrive una modifica del DOM osservata da un MutationObserver. I record vengono passati nell’array fornito alla funzione di callback dell’observer; è possibile recuperare i record in attesa anche con takeRecords(). È un’API del DOM, non una parte di ECMAScript. MDN la classifica come ampiamente disponibile nei browser da luglio 2015; la presenza di Node 24 in un progetto non dimostra il supporto di questa API del browser.
MutationRecord.type è "attributes", "characterData" oppure "childList". MutationRecord.target identifica, rispettivamente, l’elemento il cui attributo è cambiato, il nodo CharacterData modificato oppure il nodo la cui lista di figli è cambiata, non il figlio aggiunto o rimosso.
MutationRecord.addedNodes e MutationRecord.removedNodes sono oggetti NodeList che contengono i nodi aggiunti e rimossi da quella modifica. Ogni lista è vuota se non ci sono nodi corrispondenti. MutationRecord.attributeName contiene il nome dell’attributo modificato per "attributes" ed è null per gli altri tipi.
MutationRecord.oldValue contiene il valore precedente dell’attributo solo se attributeOldValue è attivato, oppure i dati CharacterData precedenti solo se è attivato characterDataOldValue. È inoltre necessario osservare il tipo di modifica corrispondente. Negli altri casi, compreso "childList", il valore è null; anche un attributo prima inesistente può avere un valore precedente null.
L’esempio osserva un elemento scollegato e legge i record in modo sincrono con takeRecords(), che svuota la coda. In questo modo non è necessario attendere la callback. Dopo aver recuperato i record, disconnette l’observer.
Esempi
(() => {
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
]));
}
})();Risultato
["attributes",true,0,0,"data-state","idle"] ["childList",true,1,0,null,null] ["childList",true,0,1,null,null]
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.