CKTIS / JavaScript
MutationRecord: eine DOM-Änderung auslesen
Ermittle die Art der Änderung und den betroffenen Knoten, prüfe hinzugefügte oder entfernte Kinder und erkenne, wann der Eintrag den vorherigen Wert enthält.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
const { type, target, addedNodes, removedNodes, attributeName, oldValue } = record;Ein MutationRecord beschreibt eine einzelne DOM-Änderung. Ein MutationObserver übergibt die Einträge in einem Mikrotask an seine Callback-Funktion, nicht während der Änderung selbst. Die Eigenschaften sind schreibgeschützt. Lies zuerst type, um die übrigen Felder richtig zu deuten. Diese API gehört zur Webplattform, nicht zu ECMAScript 2024. Setze ihre Verfügbarkeit in Laufzeitumgebungen ohne DOM nicht voraus.
Bei type === "childList" ist target der Knoten, dessen direkte Kinder sich geändert haben. addedNodes und removedNodes sind NodeList-Objekte mit den durch diese Änderung hinzugefügten bzw. entfernten Kindern. Wurde nichts hinzugefügt oder entfernt, ist die entsprechende Liste leer und nicht null. Beim Verschieben eines Knotens können getrennte Einträge für das Entfernen und Hinzufügen entstehen.
Bei type === "attributes" ist target das geänderte Element. attributeName enthält den lokalen Namen des Attributs ohne Namensraumpräfix. Mit attributeOldValue: true in observe() enthält oldValue den vorherigen Attributwert als Zeichenkette. Ohne diese Option oder wenn das Attribut vorher nicht existierte, ist oldValue gleich null.
Bei type === "characterData" ist target der CharacterData-Knoten selbst, etwa ein Textknoten, nicht sein Elternknoten. oldValue enthält die vorherigen Daten nur mit characterDataOldValue: true als Zeichenkette, sonst ist es null. Bei "childList" ist oldValue immer null. Außerhalb von "attributes" ist attributeName gleich null, und außerhalb von "childList" sind beide Knotenlisten leer.
Mit subtree: true kann target im Eintrag ein Nachfahre des an observe() übergebenen Knotens sein. Ein Feld newValue gibt es nicht: Beim Auslesen von target erhältst du den aktuellen Zustand, in den bereits spätere Änderungen eingeflossen sein können.
Beispiele
<!doctype html>
<meta charset="utf-8">
<title>MutationRecord example</title>
<script>
(() => {
const root = document.createElement("div");
const text = document.createTextNode("hello");
const child = document.createElement("span");
root.setAttribute("data-state", "before");
root.append(text);
const observer = new MutationObserver(() => {});
observer.observe(root, {
attributes: true,
attributeOldValue: true,
characterData: true,
characterDataOldValue: true,
childList: true,
subtree: true,
});
root.setAttribute("data-state", "after");
text.data = "world";
root.append(child);
child.remove();
const records = observer.takeRecords();
observer.disconnect();
const nodeNames = (nodes) => Array.from(nodes, (node) => node.nodeName);
for (const { type, target, addedNodes, removedNodes, attributeName, oldValue } of records) {
console.log(JSON.stringify([
type, target.nodeName, nodeNames(addedNodes), nodeNames(removedNodes),
attributeName, oldValue,
]));
}
})();
</script>Ergebnis
["attributes","DIV",[],[],"data-state","before"] ["characterData","#text",[],[],null,"hello"] ["childList","DIV",["SPAN"],[],null,null] ["childList","DIV",[],["SPAN"],null,null]
Speichere das vollständige Beispiel als HTML-Datei, öffne sie im Browser und prüfe die Ausgabe in der Konsole. `takeRecords()` liest und leert die Warteschlange vor dem Callback-Aufruf, sodass der Code vier Einträge der Reihe nach ausgibt. Der Eintrag zum Hinzufügen enthält weiterhin `SPAN`, obwohl der Knoten später entfernt wurde.
Zugehörige Lektionen
- JavaScript · Lektion 31 · Mittlere Stufe · Version: 3
Quellen
- MutationRecord
- MutationRecord: target property
- MutationRecord: addedNodes property
- MutationRecord: removedNodes property
- MutationRecord: attributeName property
- MutationRecord: oldValue property
- MutationObserver: observe() method
- MutationObserver: takeRecords() method
- Using microtasks in JavaScript with queueMicrotask()