WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

MutationRecord – ein DOM-Änderungsdatensatz

MutationRecord beschreibt eine einzelne beobachtete DOM-Änderung. Erfahre, wie du ihren Typ und den betroffenen Knoten bestimmst, hinzugefügte und entfernte Knoten untersuchst sowie den Attributnamen und den vorherigen Wert abrufst.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

record.type; record.target; record.addedNodes; record.removedNodes; record.attributeName; record.oldValue

MutationRecord ist eine schreibgeschützte Schnittstelle, die eine von einem MutationObserver beobachtete DOM-Änderung beschreibt. Die Datensätze werden in dem Array übergeben, das an den Callback des Observers geht; ausstehende Datensätze lassen sich auch mit takeRecords() abrufen. Dies ist eine DOM-API und kein Bestandteil von ECMAScript selbst. MDN stuft sie seit Juli 2015 als breit in Browsern verfügbar ein; dass ein Projekt Node 24 verwendet, belegt nicht die Unterstützung dieser Browser-API.

MutationRecord.type hat den Wert "attributes", "characterData" oder "childList". MutationRecord.target bezeichnet jeweils das Element, dessen Attribut geändert wurde, den geänderten CharacterData-Knoten oder den Knoten, dessen Kindliste geändert wurde – nicht das hinzugefügte oder entfernte Kind.

MutationRecord.addedNodes und MutationRecord.removedNodes sind NodeList-Objekte mit den Knoten, die durch die jeweilige Änderung hinzugefügt oder entfernt wurden. Gibt es keine entsprechenden Knoten, ist die jeweilige Liste leer. MutationRecord.attributeName enthält bei "attributes" den Namen des geänderten Attributs und ist bei anderen Typen null.

MutationRecord.oldValue enthält den vorherigen Attributwert nur, wenn attributeOldValue aktiviert ist, beziehungsweise die vorherigen CharacterData-Daten nur, wenn characterDataOldValue aktiviert ist. Außerdem muss die entsprechende Art von Änderung beobachtet werden. Andernfalls, auch bei "childList", ist der Wert null; bei einem zuvor nicht vorhandenen Attribut kann der alte Wert ebenfalls null sein.

Das Beispiel beobachtet ein abgetrenntes Element und liest die Datensätze synchron mit takeRecords() aus, wodurch die Warteschlange geleert wird. So muss nicht auf den Callback gewartet werden. Nach dem Abrufen der Datensätze wird der Observer getrennt.

Beispiele

(() => {
  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
    ]));
  }
})();

Ergebnis

["attributes",true,0,0,"data-state","idle"]
["childList",true,1,0,null,null]
["childList",true,0,1,null,null]

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen