CKTIS / JavaScript
Opzioni di MutationObserver: tipi di mutazione, sottoalbero, filtro e valori precedenti
Configura `observe()` per seguire le modifiche ai nodi figli, agli attributi o ai dati dei caratteri. Scegli l’ambito dell’osservazione e quando conservare il valore precedente.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
const observer = new MutationObserver((records, observer) => {
for (const record of records) {
// Read record.type, record.target, or record.oldValue.
}
});
observer.observe(target, {
childList: true,
attributes: true,
characterData: true,
subtree: true,
attributeFilter: ["data-state"],
attributeOldValue: true,
characterDataOldValue: true,
});new MutationObserver(callback) crea un osservatore; observer.observe(target, options) avvia l’osservazione di un nodo del DOM. La funzione di callback riceve un array di oggetti MutationRecord e l’osservatore. È un’API DOM della piattaforma web, non fa parte di ECMAScript 2024; la disponibilità dipende dall’ambiente di esecuzione.
childList segnala l’aggiunta o la rimozione di figli diretti di un nodo osservato (addedNodes, removedNodes). attributes segnala l’aggiunta, la modifica e la rimozione degli attributi di un elemento. characterData segnala le modifiche a un nodo CharacterData esistente, per esempio quando cambia text.data. Assegnare un valore a textContent di un elemento ne sostituisce i figli: se cambia l’elenco dei figli, la mutazione è childList, non characterData. subtree: true estende ai discendenti i tipi di mutazione selezionati; per impostazione predefinita si osserva soltanto target.
attributeFilter elenca nomi locali di attributi, non selettori CSS. Con un filtro corrispondono solo gli attributi elencati e senza spazio dei nomi; senza filtro sono ammessi tutti gli attributi. attributeOldValue: true e characterDataOldValue: true salvano il valore precedente alla mutazione corrispondente nella proprietà di sola lettura record.oldValue. Non esistono un’opzione oldValue né un campo newValue. oldValue è null per childList, se il valore precedente non è stato richiesto o se l’attributo prima non esisteva.
childList vale false per impostazione predefinita. Se attributes è omesso, diventa true quando è specificato attributeFilter o attributeOldValue; se characterData è omesso, diventa true quando è specificato characterDataOldValue. Per le opzioni del valore precedente basta che siano presenti, anche se valgono false. Altrimenti entrambi i tipi sono disattivati per impostazione predefinita. observe() genera un TypeError se nessun tipo è attivo, se attributes: false è combinato con un filtro o con attributeOldValue: true, oppure se characterData: false è combinato con characterDataOldValue: true.
I record arrivano alla funzione di callback in gruppi, in un microtask, non durante la modifica del DOM. Con subtree: true, le registrazioni temporanee consentono di continuare a osservare il sottoalbero di un discendente rimosso. Il microtask di notifica elimina queste registrazioni quando elabora l’osservatore, prima di un’eventuale chiamata alla funzione di callback. Questa operazione non richiede la consegna di un record di rimozione: childList può essere disattivato oppure takeRecords() può avere già svuotato la coda. disconnect() interrompe l’osservazione e scarta i record in attesa; per recuperarli, chiama prima takeRecords(), che svuota la coda.
Esempi
<!doctype html>
<meta charset="utf-8">
<title>MutationObserver options</title>
<script>
const root = document.createElement("div");
const item = document.createElement("span");
const text = document.createTextNode("before");
item.setAttribute("data-state", "idle");
item.append(text);
root.append(item);
const observer = new MutationObserver((records, self) => {
for (const record of records) {
console.log(JSON.stringify([record.type, record.attributeName, record.oldValue]));
}
self.disconnect();
});
observer.observe(root, {
childList: true,
subtree: true,
attributeFilter: ["data-state"],
attributeOldValue: true,
characterDataOldValue: true,
});
item.setAttribute("data-state", "ready");
item.setAttribute("title", "ignored");
text.data = "after";
item.append(document.createElement("em"));
</script>Risultato
["attributes","data-state","idle"] ["characterData",null,"before"] ["childList",null,null]
Salva l’intero esempio in un file `.html` e aprilo in un browser. Apri la console di sviluppo e ricarica la pagina. I nodi non vengono inseriti nella pagina. Il filtro esclude `title` e le opzioni per i valori precedenti attivano `attributes` e `characterData`, che sono stati omessi. La funzione di callback stampa tre record nell’ordine delle mutazioni, poi interrompe l’osservazione.
Lezioni correlate
- JavaScript · Lezione 31 · Intermedio · Versione: 3
Fonti
- MutationObserver: observe() method
- MutationObserver: MutationObserver() constructor
- MutationRecord
- MutationRecord: oldValue property
- Node: textContent property
- Using microtasks in JavaScript with queueMicrotask()
- HTML Standard — Event loops
- MutationObserver: disconnect() method
- MutationObserver: takeRecords() method