Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

MutationObserver — osservare le modifiche al DOM

MutationObserver registra modifiche selezionate del DOM e consegna i record in modo asincrono a una funzione di callback. Scopri come observe() configura l’osservazione, takeRecords() svuota la coda e disconnect() interrompe l’osservazione.

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

const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();

MutationObserver è un’API dello standard DOM, non fa parte di ECMAScript. La funzione di callback riceve un array di oggetti MutationRecord e l’observer. La notifica viene accodata come microtask, quindi non viene consegnata in modo sincrono durante una modifica; una chiamata può contenere più record. La presenza di Node 24 in un repository non dimostra la disponibilità di questa API del browser.

MutationObserver.observe, chiamato come observer.observe(target, options), seleziona un nodo e i tipi di mutazione: childList rileva l’aggiunta e la rimozione di figli, attributes rileva gli attributi e characterData i dati dei nodi di testo e simili. subtree: true include i discendenti. Dopo l’applicazione dei valori predefiniti, deve essere attivato almeno un tipo; altrimenti viene generato un TypeError. attributeFilter limita i nomi degli attributi; attributeOldValue e characterDataOldValue richiedono i valori precedenti. Le opzioni relative agli attributi o ai dati possono attivare implicitamente il rispettivo tipo di osservazione, ma impostazioni esplicitamente in conflitto generano un TypeError.

MutationObserver.takeRecords, chiamato come observer.takeRecords(), restituisce sincronicamente i record in attesa e svuota la coda senza invocare la funzione di callback né interrompere l’osservazione. MutationObserver.disconnect, chiamato come observer.disconnect(), interrompe tutte le osservazioni di questo oggetto e scarta i record in attesa. Recuperali prima se ti servono. L’oggetto può essere riavviato con observe().

L’esempio osserva un elemento scollegato, recupera il record prima della consegna della notifica e interrompe l’osservazione. oldValue è null perché l’attributo prima non esisteva. Limita l’ambito dell’osservazione; le modifiche apportate dalla funzione di callback possono generare ulteriori notifiche.

Esempi

{
  const target = document.createElement('div');
  const observer = new MutationObserver((records) => {
    console.log('callback:', records.length);
  });

  observer.observe(target, {
    attributes: true,
    attributeFilter: ['data-state'],
    attributeOldValue: true
  });

  target.setAttribute('data-state', 'ready');
  const records = observer.takeRecords();
  console.log(JSON.stringify(records.map((record) => ({
    type: record.type,
    attributeName: record.attributeName,
    oldValue: record.oldValue
  }))));

  observer.disconnect();
  target.setAttribute('data-state', 'done');
  console.log(observer.takeRecords().length);
}

Risultato

[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0

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