CKTIS / JavaScript
MutationObserver — DOM-Änderungen beobachten
MutationObserver erfasst ausgewählte DOM-Änderungen und übergibt die Datensätze asynchron an eine Callback-Funktion. Erfahre, wie observe() die Beobachtung konfiguriert, takeRecords() die Warteschlange leert und disconnect() die Beobachtung beendet.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();MutationObserver ist eine API des DOM-Standards und kein Bestandteil von ECMAScript selbst. Die Callback-Funktion erhält ein Array von MutationRecord-Objekten und den Observer. Die Benachrichtigung wird als Microtask eingereiht und nicht synchron während einer Änderung zugestellt; ein Aufruf kann mehrere Datensätze enthalten. Dass Node 24 in einem Repository vorhanden ist, belegt nicht die Verfügbarkeit dieser Browser-API.
MutationObserver.observe, aufgerufen als observer.observe(target, options), legt einen Knoten und die Änderungstypen fest: childList erfasst das Hinzufügen und Entfernen von Kindknoten (auch Text- und Kommentarknoten), attributes Attribute und characterData Daten von Textknoten und ähnlichen Knoten. subtree: true schließt Nachfahren ein. Nach Anwendung der Standardwerte muss mindestens ein Typ aktiviert sein, sonst wird ein TypeError ausgelöst. attributeFilter schränkt die Attributnamen ein; attributeOldValue und characterDataOldValue fordern die vorherigen Werte an. Attribut- oder datenbezogene Optionen können den entsprechenden Beobachtungstyp implizit aktivieren; ausdrücklich widersprüchliche Einstellungen lösen jedoch einen TypeError aus.
MutationObserver.takeRecords, aufgerufen als observer.takeRecords(), gibt ausstehende Datensätze synchron zurück und leert die Warteschlange, ohne die Callback-Funktion aufzurufen oder die Beobachtung zu beenden. MutationObserver.disconnect, aufgerufen als observer.disconnect(), beendet alle Beobachtungen dieses Objekts und verwirft ausstehende Datensätze. Rufe sie vorher ab, falls du sie benötigst. Das Objekt kann mit observe() erneut gestartet werden.
Das Beispiel beobachtet ein abgetrenntes Element, ruft den Datensatz vor der Zustellung der Benachrichtigung ab und beendet die Beobachtung. oldValue ist null, weil das Attribut zuvor nicht vorhanden war. Beschränke den Beobachtungsbereich; Änderungen durch die Callback-Funktion können weitere Benachrichtigungen auslösen.
Beispiele
{
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);
}Ergebnis
[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.