Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

Opcje MutationObserver: typy zmian, poddrzewo, filtr i poprzednie wartości

Skonfiguruj `observe()`, aby śledzić zmiany listy dzieci, atrybutów lub danych znakowych. Wybierz zasięg obserwacji i zdecyduj, kiedy rekord ma zawierać poprzednią wartość.

Wersja: ECMAScript 2024 and the current web platform; runtime support varies

Składnia

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) tworzy obserwator, ale dopiero observer.observe(target, options) rozpoczyna obserwację wskazanego węzła DOM. Funkcja zwrotna otrzymuje tablicę rekordów MutationRecord i obserwator. To API DOM platformy WWW, nie część ECMAScript 2024; dostępność zależy od środowiska uruchomieniowego.

childList wykrywa dodanie lub usunięcie bezpośrednich dzieci obserwowanego węzła (addedNodes, removedNodes). attributes wykrywa dodanie, zmianę lub usunięcie atrybutów elementu. characterData wykrywa zmianę danych istniejącego węzła CharacterData, np. zmianę text.data. Przypisanie do textContent elementu zastępuje jego dzieci, więc jeśli zmienia ich listę, powstaje rekord childList, a nie characterData. subtree: true rozszerza wybrane typy zmian na potomków; domyślnie obserwowany jest tylko target.

attributeFilter to lista lokalnych nazw atrybutów, nie selektorów CSS. Gdy podasz listę, pasują tylko wymienione atrybuty bez przestrzeni nazw; bez filtra obserwacja obejmuje wszystkie atrybuty. attributeOldValue: true i characterDataOldValue: true zapisują poprzednią wartość odpowiedniego typu zmiany w tylko do odczytu właściwości record.oldValue. Nie ma opcji oldValue ani pola newValue. oldValue wynosi null dla childList, gdy nie zamówiono zapisu poprzedniej wartości lub gdy atrybut wcześniej nie istniał.

Pominięte childList ma wartość false. Pominięte attributes staje się true, jeśli podano attributeFilter lub attributeOldValue; pominięte characterData staje się true, jeśli podano characterDataOldValue. Liczy się obecność opcji zapisu, nawet z wartością false. W pozostałych przypadkach oba typy są domyślnie wyłączone. observe() zgłasza TypeError, jeśli żaden z trzech typów nie jest włączony, jeśli attributes: false występuje z filtrem lub attributeOldValue: true, albo jeśli characterData: false występuje z characterDataOldValue: true.

Rekordy trafiają do funkcji zwrotnej partiami w mikrozadaniu, a nie w trakcie zmiany DOM. Przy subtree: true tymczasowe rejestracje pozwalają nadal obserwować odłączone poddrzewo potomka. Mikrozadanie powiadamiania usuwa te rejestracje podczas obsługi obserwatora, zanim ewentualnie wywoła funkcję zwrotną. Usunięcie rejestracji nie wymaga dostarczenia rekordu usunięcia węzła: opcja childList może być wyłączona albo takeRecords() mogło już opróżnić kolejkę. disconnect() kończy obserwację i odrzuca oczekujące rekordy; jeśli są potrzebne, najpierw pobierz je przez takeRecords(), które opróżnia kolejkę.

Przykłady

<!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>

Wynik

["attributes","data-state","idle"]
["characterData",null,"before"]
["childList",null,null]

Zapisz cały przykład jako plik `.html` i otwórz go w przeglądarce. Otwórz konsolę deweloperską i odśwież stronę. Węzły nie są dołączane do strony. Filtr pomija `title`, a opcje zapisu poprzednich wartości włączają pominięte `attributes` i `characterData`. Funkcja zwrotna wypisuje trzy rekordy w kolejności zmian, po czym zatrzymuje obserwację.

Powiązane lekcje

  • JavaScript · Lekcja 31 · Średniozaawansowany · Wersja: 3

Źródła