CKTIS / JavaScript
MutationObserver-Optionen: Änderungstypen, Teilbaum, Filter und alte Werte
Lege mit `observe()` fest, ob Änderungen an Kindknoten, Attributen oder Zeichendaten erfasst werden, wie weit die Beobachtung reicht und wann ein Eintrag den alten Wert enthält.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
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) erstellt einen Beobachter. Erst observer.observe(target, options) beginnt, einen DOM-Knoten zu beobachten. Die Callback-Funktion erhält ein Array aus MutationRecord-Objekten und den Beobachter. Das ist eine DOM-API der Webplattform, kein Teil von ECMAScript 2024; die Verfügbarkeit hängt von der Laufzeitumgebung ab.
childList meldet, wenn einem beobachteten Knoten direkte Kindknoten hinzugefügt oder entnommen werden (addedNodes, removedNodes). attributes meldet hinzugefügte, geänderte und entfernte Attribute von Elementen. characterData meldet Änderungen an einem vorhandenen CharacterData-Knoten, etwa an text.data. Wer textContent eines Elements setzt, ersetzt dessen Kindknoten. Eine daraus folgende Änderung der Kindliste wird als childList gemeldet, nicht als characterData. subtree: true weitet die gewählten Änderungstypen auf Nachfahren aus; standardmäßig wird nur target beobachtet.
attributeFilter enthält lokale Attributnamen, keine CSS-Selektoren. Mit Filter zählen nur aufgeführte Attribute ohne Namensraum; ohne Filter kommen alle Attribute infrage. attributeOldValue: true und characterDataOldValue: true speichern den Wert vor der jeweiligen Änderung in der schreibgeschützten Eigenschaft record.oldValue. Es gibt weder eine Option oldValue noch ein Feld newValue. oldValue ist null bei childList, wenn kein alter Wert angefordert wurde oder wenn das Attribut vorher nicht existierte.
childList ist standardmäßig false. Fehlt attributes, wird es true, sobald attributeFilter oder attributeOldValue angegeben ist. Fehlt characterData, wird es true, sobald characterDataOldValue angegeben ist. Bei den Optionen für alte Werte zählt schon die Angabe, auch mit false. Ansonsten sind beide Änderungstypen standardmäßig aus. observe() löst einen TypeError aus, wenn kein Änderungstyp aktiv ist, wenn attributes: false mit einem Filter oder attributeOldValue: true kombiniert wird oder wenn characterData: false mit characterDataOldValue: true kombiniert wird.
Die Callback-Funktion erhält die Einträge gesammelt in einem Mikrotask, nicht während der DOM-Änderung selbst. Bei subtree: true kann der Teilbaum eines entfernten Nachfahren durch vorübergehende Registrierungen weiter beobachtet werden. Der Benachrichtigungs-Mikrotask entfernt diese Registrierungen, wenn er den Beobachter verarbeitet, noch vor einem etwaigen Aufruf der Callback-Funktion. Dazu muss kein Eintrag über das Entfernen zugestellt werden: childList kann deaktiviert sein oder takeRecords() kann die Warteschlange bereits geleert haben. disconnect() beendet die Beobachtung und verwirft ausstehende Einträge. Wer sie noch braucht, leert zuerst mit takeRecords() die Warteschlange und erhält dabei die Einträge.
Beispiele
<!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>Ergebnis
["attributes","data-state","idle"] ["characterData",null,"before"] ["childList",null,null]
Speichere das gesamte Beispiel als `.html`-Datei und öffne sie in einem Browser. Öffne die Entwicklerkonsole und lade die Seite neu. Die Knoten werden nicht in die Seite eingefügt. Der Filter schließt `title` aus; die Optionen für alte Werte aktivieren die nicht angegebenen Optionen `attributes` und `characterData`. Die Callback-Funktion gibt drei Einträge in Änderungsreihenfolge aus und beendet dann die Beobachtung.
Zugehörige Lektionen
- JavaScript · Lektion 31 · Mittlere Stufe · Version: 3
Quellen
- 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