CKTIS / JavaScript
MutationRecord — rekord zmiany DOM
MutationRecord opisuje pojedynczą zaobserwowaną zmianę DOM. Dowiedz się, jak rozpoznać jej typ, wskazać zmieniony węzeł, odczytać dodane i usunięte węzły oraz uzyskać nazwę atrybutu i poprzednią wartość.
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
record.type; record.target; record.addedNodes; record.removedNodes; record.attributeName; record.oldValueMutationRecord to interfejs tylko do odczytu opisujący zmianę DOM obserwowaną przez MutationObserver. Rekordy trafiają do tablicy przekazywanej do funkcji zwrotnej obserwatora; można też pobrać oczekujące rekordy metodą takeRecords(). To API DOM, a nie element samego ECMAScript. MDN klasyfikuje je jako szeroko dostępne w przeglądarkach od lipca 2015 r.; obecność Node 24 w projekcie nie dowodzi obsługi tego API przeglądarkowego.
MutationRecord.type ma wartość "attributes", "characterData" albo "childList". MutationRecord.target wskazuje odpowiednio element ze zmienionym atrybutem, zmieniony węzeł CharacterData albo węzeł, którego lista dzieci się zmieniła — nie dodane lub usunięte dziecko.
MutationRecord.addedNodes i MutationRecord.removedNodes to obiekty NodeList zawierające węzły dodane i usunięte w danej zmianie. Jeśli odpowiednich węzłów nie ma, lista jest pusta. MutationRecord.attributeName zawiera nazwę zmienionego atrybutu dla "attributes", a dla pozostałych typów wynosi null.
MutationRecord.oldValue zawiera poprzednią wartość atrybutu tylko przy włączonym attributeOldValue, a poprzednie dane CharacterData tylko przy włączonym characterDataOldValue. Trzeba też obserwować odpowiedni rodzaj zmian. W pozostałych przypadkach, w tym dla "childList", wynosi null; dla wcześniej nieistniejącego atrybutu również może wynosić null.
Przykład obserwuje odłączony element i odczytuje rekordy synchronicznie przez takeRecords(), które opróżnia kolejkę. Dzięki temu nie trzeba czekać na funkcję zwrotną. Po pobraniu rekordów obserwator jest odłączany.
Przykłady
(() => {
const root = document.createElement("div");
root.setAttribute("data-state", "idle");
const observer = new MutationObserver(() => {});
observer.observe(root, {
attributes: true,
attributeOldValue: true,
childList: true
});
root.setAttribute("data-state", "ready");
const child = document.createElement("span");
root.appendChild(child);
root.removeChild(child);
const records = observer.takeRecords();
observer.disconnect();
for (const record of records) {
console.log(JSON.stringify([
record.type,
record.target === root,
record.addedNodes.length,
record.removedNodes.length,
record.attributeName,
record.oldValue
]));
}
})();Wynik
["attributes",true,0,0,"data-state","idle"] ["childList",true,1,0,null,null] ["childList",true,0,1,null,null]
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.