MutationObserver#

MutationObserver.observe()#

Metoda observe() rejestruje danego obserwatora zmian dla przekazanego węzła, z jednoczesnym określeniem szczegółowych kryteriów rejestracji przyszłych zmian w węźle (lub też jego potomkach). Obserwator zmian, na którym wywołano opisywaną metodę, staje się zarejestrowanym obserwatorem.

Opis działania#

Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
mutationObserver.observe(target, options);

gdzie poszczególne człony oznaczają:

Algorytm wywołania metody observe(target, options) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

  1. Jeśli właściwość attributeOldValue lub attributeFilter w options jest obecna i właściwość attributes w options jest nieobecna, to ustaw właściwość attributes w options na boolowską wartość true.
  2. Jeśli właściwość characterDataOldValue w options jest obecna i właściwość characterData w options jest nieobecna, to ustaw właściwość characterData w options na boolowską wartość true.
  3. Jeśli przynajmniej jedna z właściwości childList, attributes lub characterData w options nie ma boolowskiej wartości true, to zrzuć błąd TypeError.
  4. Jeśli właściwość attributeOldValue w options ma boolowską wartość true i właściwość attributes w options ma boolowską wartość false, to zrzuć błąd TypeError.
  5. Jeśli właściwość attributeFilter w options jest obecna i właściwość attributes w options ma boolowską wartość false, to zrzuć błąd TypeError.
  6. Jeśli właściwość characterDataOldValue w options ma boolowską wartość true i właściwość characterData w options ma boolowską wartość false, to zrzuć błąd TypeError.

  7. Dla każdego (for each) zarejestrowanego obserwatora registered w liście zarejestrowanych obserwatorów skojarzonej z target, którego obserwatorem jest obiekt kontekstu, wykonaj poniższe podkroki:

    1. Usuń wszystkich przejściowych zarejestrowanych obserwatorów, których źródłem jest registered.
    2. Zastąp opcje w registered przez options.
  8. W przeciwnym razie dodaj nowego zarejestrowanego obserwatora do listy zarejestrowanych obserwatorów skojarzonej z target, dla którego obiekt kontekstu będzie obserwatorem i options będzie opcjami, a następnie dodaj target do listy węzłów skojarzonej z obiektem kontekstu, na których jest on rejestrowany.

Najciekawsza sytuacja ma miejsce w przypadku drugiego argumentu przekazanego do metody observe(). W ujęciu Web IDL mamy do czynienia ze słownikiem. Nie ma potrzeby wypisywania wszystkich właściwości w słowniku, no chyba że planujemy szerszą konkretyzację rejestrowanych zmian dla węzłów. Niektórzy członkowie słownika będą ustawiani automatycznie w zależności od wartości/obecności innych członków słownika (co widać w powyższym algorytmie). Jest to zamierzone i ma na celu zwiększenie elastyczności całego mechanizmu.

Prosty przykład:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
<script>

	// Tworzymy nowego obserwatora 'newObserver'
	var newObserver = new MutationObserver(function(records, observer){

		// W czasie wywołania funkcji zwrotnej mamy dostęp do:
		// records - lista ze wszystkimi obiektami MutationRecord
		// observer - nasz newObserwer

		var getInfo = "";
		var recordsLen = records.length;

		for (var i = 0; i < recordsLen; i++){

			var record = records[i];

			getInfo += "<br><br>" + "records[" + i + "]: " + record
				+ "<br>" + "record.type: " + record.type
				+ "<br>" + "record.target: " + record.target
				+ "<br>" + "record.addedNodes.length: " + record.addedNodes.length
				+ "<br>" + "record.attributeName: " + record.attributeName
				+ "<br>" + "record.attributeNamespace: " + record.attributeNamespace
				+ "<br>" + "record.oldValue: " + record.oldValue;
		}

		document.documentElement.innerHTML += "Liczba zmian records.length: " + recordsLen
			+ "<br><br>" + "Odczytujemy poszczególne dane każdej zmiany:"
			+ getInfo;

	});

	// Tworzymy obiekt konfiguracyjny
	var config = {
		childList: true,
		attributes: true,
		attributeOldValue: true,
		attributeFilter: ["id", "name"],
		subtree: true,
		characterDataOldValue: true
	};

	var new_P = document.createElement("P");
	newObserver.observe(new_P, config); // rejestrujemy 'newObserver' na węźle 'new_P'

	// Przeprowadzamy różne zmiany na węźle 'new_P' i jego zawartości
	new_P.id = "id1";
	new_P.id = "id2";
	new_P.id = "id2";
	new_P.className = "important"; // ten atrybut nie podlega obserwacji
	new_P.appendChild(document.createElement("span"));
	new_P.textContent = "Start";
	new_P.childNodes[0].textContent = "Witam1";
	new_P.childNodes[0].textContent = "Witam2";
	new_P.childNodes[0].textContent = "Witam2";

</script>

Metoda observe() pojawia się dopiero w specyfikacji DOM4.

Składnia Web IDL#

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
interface MutationObserver {
	void observe(Node target, MutationObserverInit options);
}

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

MutationObserver (H1) MutationObserver.observe() (H2) Opis działania (H3) Składnia Web IDL (H3) Specyfikacje i inne materiały (H3)