Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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

MutationRecord è 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.

Fonti