CKTIS / JavaScript
MutationObserver: observe(), disconnect() e takeRecords()
Osserva modifiche selezionate del DOM, recupera i record in attesa senza aspettare il callback e decidi se conservarli quando interrompi l’osservazione.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();new MutationObserver(callback) crea un osservatore senza avviare l’osservazione. observe(target, options), disconnect() e takeRecords() sono metodi di istanza, non metodi statici. Le modifiche corrispondenti vengono accodate; un microtask di notifica le passa in gruppo a callback(records, observer), invece di chiamare la funzione in modo sincrono per ogni modifica.
observe(target, options) registra un nodo del DOM (Node) e restituisce undefined. Altre chiamate possono aggiungere nodi da osservare o aggiornare le opzioni per lo stesso nodo. childList rileva aggiunte e rimozioni di figli diretti, attributes rileva le modifiche agli attributi e characterData quelle ai dati di un nodo, per esempio al contenuto di un nodo di testo. subtree: true applica le stesse regole ai discendenti. Le modifiche in un ramo rimosso possono ancora essere accodate prima del microtask di notifica successivo.
attributeFilter limita i nomi degli attributi osservati. attributeOldValue: true e characterDataOldValue: true salvano il valore precedente in oldValue. Se attributes è omesso, indicare attributeFilter o attributeOldValue abilita l’osservazione degli attributi; allo stesso modo, indicare characterDataOldValue abilita characterData se omesso. observe() genera un TypeError se non è abilitato alcun tipo di modifica, se attributes: false è abbinato a un filtro o ad attributeOldValue: true, oppure se characterData: false è abbinato a characterDataOldValue: true.
takeRecords() restituisce in modo sincrono un array di oggetti MutationRecord in attesa ([] se la coda è vuota) e svuota la coda. Non interrompe l’osservazione e non chiama il callback: elabori tu i record restituiti. disconnect() restituisce undefined, interrompe l’osservazione di tutti i nodi registrati da quell’istanza e scarta i record non consegnati. Per conservarli, chiama takeRecords() subito prima di disconnect(). Puoi riutilizzare l’osservatore chiamando di nuovo observe().
È un’API DOM della piattaforma web, non fa parte di ECMAScript 2024. La disponibilità dipende dall’ambiente di esecuzione. L’osservatore non concede accesso a nodi altrimenti inaccessibili, come quelli in un iframe di origine diversa.
Esempi
<!doctype html>
<meta charset="utf-8">
<title>MutationObserver example</title>
<script>
const target = document.createElement('div');
const options = { attributes: true, attributeFilter: ['data-state'] };
const observer = new MutationObserver((records, currentObserver) => {
console.log(`callback: ${records.length} ${records[0].attributeName}`);
currentObserver.disconnect();
});
observer.observe(target, options);
target.setAttribute('data-state', 'first');
const [record] = observer.takeRecords();
console.log(`taken: ${record.type} ${record.attributeName}`);
target.setAttribute('data-state', 'discarded');
observer.disconnect();
target.setAttribute('data-state', 'unobserved');
console.log(`remaining: ${observer.takeRecords().length}`);
observer.observe(target, options);
target.setAttribute('data-state', 'delivered');
</script>Risultato
taken: attributes data-state remaining: 0 callback: 1 data-state
Salva l’intero esempio come file HTML, aprilo in un browser e controlla l’output nella console per sviluppatori. L’elemento non è inserito nella pagina. `takeRecords()` recupera il primo record, `disconnect()` scarta il secondo e la modifica durante l’interruzione non viene registrata. Solo la modifica successiva alla ripresa arriva al callback.
Lezioni correlate
- JavaScript · Lezione 31 · Intermedio · Versione: 3