CKTIS / JavaScript
MutationObserver: observe(), disconnect() und takeRecords()
Beobachte ausgewählte DOM-Änderungen, hole ausstehende Einträge ohne Warten auf die Callback-Funktion ab und entscheide beim Beenden, ob du die Einträge behalten willst.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();new MutationObserver(callback) erstellt einen Beobachter, startet ihn aber noch nicht. observe(target, options), disconnect() und takeRecords() sind Instanzmethoden, keine statischen Methoden. Passende Änderungen landen in einer Warteschlange; ein Benachrichtigungs-Mikrotask übergibt sie gesammelt an callback(records, observer), statt die Funktion bei jeder Änderung synchron aufzurufen.
observe(target, options) registriert einen DOM-Knoten (Node) und gibt undefined zurück. Weitere Aufrufe können andere Ziele hinzufügen oder die Optionen für dasselbe Ziel ändern. childList erfasst hinzugefügte und entfernte direkte Kindknoten, attributes Attributänderungen und characterData Änderungen an Knotendaten, etwa am Inhalt eines Textknotens. subtree: true wendet dieselben Regeln auf Nachfahren an. Änderungen in einem entfernten Zweig können noch vor dem nächsten Benachrichtigungs-Mikrotask in die Warteschlange gelangen.
attributeFilter beschränkt die beobachteten Attributnamen. attributeOldValue: true und characterDataOldValue: true speichern den vorherigen Wert in oldValue. Fehlt attributes, aktiviert schon die Angabe von attributeFilter oder attributeOldValue die Attributbeobachtung. Bei fehlendem characterData gilt dasselbe für characterDataOldValue. observe() wirft einen TypeError, wenn kein Änderungstyp aktiviert ist, wenn attributes: false mit einem Filter oder attributeOldValue: true kombiniert wird oder wenn characterData: false mit characterDataOldValue: true kombiniert wird.
takeRecords() gibt synchron ein Array ausstehender MutationRecord-Objekte zurück ([] bei leerer Warteschlange) und leert die Warteschlange. Die Methode beendet weder die Beobachtung noch ruft sie den Callback auf. Du verarbeitest die Einträge selbst. disconnect() gibt undefined zurück, beendet die Beobachtung aller Ziele dieser Instanz und verwirft ausstehende Einträge. Um sie zu behalten, rufe takeRecords() unmittelbar vor disconnect() auf. Mit observe() kannst du den Beobachter erneut verwenden.
Das ist eine DOM-API der Webplattform, kein Bestandteil von ECMAScript 2024. Die Verfügbarkeit hängt von der Laufzeitumgebung ab. Der Beobachter gewährt keinen zusätzlichen Zugriff auf Knoten, etwa innerhalb eines iframe mit anderem Ursprung.
Beispiele
<!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>Ergebnis
taken: attributes data-state remaining: 0 callback: 1 data-state
Speichere das gesamte Beispiel als HTML-Datei, öffne sie im Browser und prüfe die Ausgabe in der Entwicklerkonsole. Das Element wird nicht in die Seite eingefügt. `takeRecords()` holt den ersten Eintrag ab, `disconnect()` verwirft den zweiten, und die Änderung während der Unterbrechung wird nicht erfasst. Nur die Änderung nach dem Neustart erreicht den Callback.
Zugehörige Lektionen
- JavaScript · Lektion 31 · Mittlere Stufe · Version: 3