Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

MutationObserver — obserwowanie zmian DOM

MutationObserver rejestruje wybrane zmiany DOM i przekazuje rekordy do funkcji zwrotnej asynchronicznie. Poznaj konfigurację observe(), opróżnianie kolejki przez takeRecords() i zatrzymywanie obserwacji przez disconnect().

Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Składnia

const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();

MutationObserver to API standardu DOM, a nie element samego ECMAScript. Funkcja zwrotna otrzymuje tablicę MutationRecord oraz obserwatora. Powiadomienie jest kolejkowane jako mikrozadanie, nie następuje synchronicznie przy zmianie; jedno wywołanie może obejmować wiele rekordów. Dostępność Node 24 w repozytorium nie potwierdza dostępności tego API przeglądarkowego.

MutationObserver.observe, wywoływane jako observer.observe(target, options), wybiera węzeł i rodzaje zmian: childList śledzi dodawanie i usuwanie dzieci, attributes — atrybuty, a characterData — dane węzłów tekstowych i podobnych. subtree: true obejmuje potomków. Co najmniej jeden rodzaj musi być włączony po zastosowaniu wartości domyślnych; inaczej wystąpi TypeError. attributeFilter ogranicza nazwy atrybutów; attributeOldValue i characterDataOldValue żądają poprzednich wartości. Opcje dotyczące atrybutów lub danych mogą domyślnie włączyć odpowiedni rodzaj obserwacji, ale jawnie sprzeczne ustawienia powodują TypeError.

MutationObserver.takeRecords, czyli observer.takeRecords(), synchronicznie zwraca oczekujące rekordy i opróżnia kolejkę bez wywoływania funkcji zwrotnej ani zatrzymywania obserwacji. MutationObserver.disconnect, czyli observer.disconnect(), zatrzymuje wszystkie obserwacje tego obiektu i odrzuca oczekujące rekordy. Jeśli są potrzebne, pobierz je wcześniej. Obiekt można ponownie uruchomić przez observe().

Przykład obserwuje odłączony element, pobiera rekord przed dostarczeniem powiadomienia i kończy obserwację. oldValue wynosi null, ponieważ atrybut wcześniej nie istniał. Ogranicz zakres obserwacji; zmiany wykonywane przez funkcję zwrotną mogą tworzyć kolejne powiadomienia.

Przykłady

{
  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);
}

Wynik

[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła