CKTIS / JavaScript
MutationObserver: observe(), disconnect() i takeRecords()
Obserwuj wybrane zmiany w DOM, pobieraj oczekujące rekordy bez czekania na funkcję zwrotną i kończ obserwację świadomie: zachowując lub odrzucając kolejkę.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
const observer = new MutationObserver(callback);
observer.observe(target, options);
const records = observer.takeRecords();
observer.disconnect();new MutationObserver(callback) tworzy obserwator, ale nie rozpoczyna obserwacji. observe(target, options), disconnect() i takeRecords() to metody instancji, nie konstruktora. Pasujące zmiany trafiają do kolejki; mikrozadanie powiadamiające przekazuje je partią do callback(records, observer), a nie wywołuje funkcji synchronicznie przy każdej zmianie.
observe(target, options) rejestruje węzeł DOM (Node) i zwraca undefined. Kolejne wywołania mogą dodać inne węzły albo zmienić opcje dla tego samego węzła. childList wykrywa dodawanie i usuwanie bezpośrednich dzieci, attributes — zmiany atrybutów, a characterData — zmiany danych węzła, np. tekstowego. subtree: true stosuje te same reguły także do potomków. Zmiany w usuniętej gałęzi mogą jeszcze trafić do kolejki przed najbliższym mikrozadaniem powiadamiającym.
attributeFilter ogranicza obserwację do wskazanych nazw atrybutów. attributeOldValue: true i characterDataOldValue: true zapisują poprzednią wartość w oldValue. Gdy pominięto attributes, sama obecność attributeFilter lub attributeOldValue włącza obserwację atrybutów; obecność characterDataOldValue działa analogicznie dla pominiętego characterData. observe() zgłasza TypeError, jeśli żaden typ zmian nie jest włączony, jeśli przy attributes: false podano filtr lub attributeOldValue: true, albo jeśli przy characterData: false ustawiono characterDataOldValue: true.
takeRecords() synchronicznie zwraca tablicę oczekujących obiektów MutationRecord ([], gdy kolejka jest pusta) i opróżnia kolejkę. Nie zatrzymuje obserwacji ani nie wywołuje funkcji zwrotnej. Pobrane rekordy przetwarzasz samodzielnie. disconnect() zwraca undefined, zatrzymuje obserwację wszystkich celów tej instancji i odrzuca nieodebrane rekordy. Aby je zachować, wywołaj takeRecords() bezpośrednio przed disconnect(). Obserwator można uruchomić ponownie przez observe().
To API DOM platformy WWW, nie część ECMAScript 2024. Dostępność zależy od środowiska wykonawczego. Obserwator nie daje dostępu do węzłów, do których dostęp jest zablokowany, np. wewnątrz ramki iframe o innym pochodzeniu.
Przykłady
<!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>Wynik
taken: attributes data-state remaining: 0 callback: 1 data-state
Zapisz cały przykład jako plik HTML, otwórz go w przeglądarce i sprawdź komunikaty w konsoli deweloperskiej. Element nie jest dołączony do strony. Pierwszy rekord odbiera `takeRecords()`, drugi odrzuca `disconnect()`, a zmiana podczas przerwy nie jest rejestrowana. Funkcja zwrotna otrzymuje tylko zmianę po wznowieniu obserwacji.
Powiązane lekcje
- JavaScript · Lekcja 31 · Średniozaawansowany · Wersja: 3