MutationObserver#
MutationObserver.takeRecords()#
Metoda takeRecords() zwraca sekwencję ze wszystkimi obiektami typu MutationRecord (tj. zapisami zmian) wykonanymi dla danego obserwatora zmian oraz czyści jego kolejkę zapisu. Jeśli obserwator zmian nie posiada żadnych zapisów zmian w swojej kolejce zapisu to zwrócona zostanie pusta sekwencja.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var records = mutationObserver.takeRecords();gdzie poszczególne człony oznaczają:
- records - sekwencja ze wszystkimi zapisami zmian wykonanymi dla danego obserwatora zmian. W przypadku JS odpowiednikiem sekwencja jest tablica.
- mutationObserver - obserwator zmian będący obiektem kontekstu.
Algorytm wywołania metody takeRecords() nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Zwróć kopię kolejki zapisu skojarzonej z obiektem kontekstu oraz wyczyść kolejkę zapisu skojarzoną z obiektem kontekstu.
Prosty przykład:
<script>
// Tworzymy nowego obserwatora 'newObserver'
var newObserver = new MutationObserver(function(records, observer){
// Cała funkcja zwrotna nie będzie wywoływana bo kolejka zapisu została wyczyszczona
// W czasie wywołania funkcji zwrotnej mamy dostęp do:
// records - lista ze wszystkimi obiektami MutationRecord
// observer - nasz newObserwer
alert("Witam wędrowcze");
});
// Tworzymy obiekt konfiguracyjny
var config = {
attributes: true
};
var new_P = document.createElement("P");
newObserver.observe(new_P, config); // rejestrujemy 'newObserver' na węźle 'new_P'
// 3x ustawiamy atrybut ID, co w konsekwencji doda do kolejki zapisu 3 nowe obiekty
new_P.id = "1";
new_P.id = "2";
new_P.id = "3";
// Pobieramy kopię kolejki zapisu i jednocześnie czyścimy oryginał
document.write(newObserver.takeRecords().length); // 3
document.write("<br>");
document.write(newObserver.takeRecords().length); // 0
</script>Metoda takeRecords() może być wywoływana bezpośrednio w funkcji zwrotnej, i w niektórych przypadkach może zwracać niepustą kolejkę zapisu (np. kiedy funkcja zwrotna modyfikuje obserwowane węzły).
Prosty przykład:
<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 numRecordsStart = newObserver.takeRecords().length; // 0 - kolejka zapisu została wyczyszczona automatycznie
// Modyfikujemy obserwowany węzeł przez co kolejka zapisu ulegnie zmianie
document.documentElement.innerHTML += "<br><br>" + "Zarejestrowano zmiany węzła HTML"
+ "<br>" + "Liczba zmian records.length: " + records.length
+ "<br><br>" + "Interfejs pierwszej zmiany records[0]: " + records[0]
+ "<br>" + "Rodzaj pierwszej zmiany records[0].type: " + records[0].type
+ "<br>" + "Cel pierwszej zmiany records[0].target: " + records[0].target;
var numRecordsBeforeChange = observer.takeRecords().length; // 1 - kolejka zapisu uległa zmianie
var numRecordsAfterChange = observer.takeRecords().length; // 0 - kolejka zapisu znowu jest pusta
document.documentElement.innerHTML += "<br><br>" + "Pobranie kolejki zapisu na początku funkcji zwrotnej: " + numRecordsStart
+ "<br>" + "Pierwsze pobranie kolejki zapisu po zmianach: " + numRecordsBeforeChange
+ "<br>" + "Drugie pobranie kolejki zapisu po zmianach: " + numRecordsAfterChange;
observer.disconnect(); // wyłączamy obserwatora (zabezpieczenie przed nieskończonym wywoływaniem)
});
// Tworzymy obiekt konfiguracyjny
var config = {
attributes: true,
childList: true,
characterData: true,
attributeFilter: ["id", "name"]
};
// Rejestrujemy 'newObserver' na konkretnym węźle (HTML),
// przekazując jednocześnie obiekt konfiguracyjny 'config'.
newObserver.observe(document.documentElement, config);
document.write(newObserver); // [object MutationObserver]
</script>Metoda takeRecords() pojawia się dopiero w specyfikacji DOM4.
Składnia Web IDL#
interface MutationObserver { sequence<MutationRecord> takeRecords(); }