MutationEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MutationEvent extends Event

Beschreibung

MutationEvent ist das Ereignisobjekt der sogenannten Mutation Events aus DOM Level 2. Diese Ereignisse werden synchron ausgelöst, sobald sich der DOM-Baum ändert – etwa wenn ein Knoten eingefügt oder entfernt wird oder sich ein Attribut bzw. Textinhalt ändert. Dazu gehören DOMNodeInserted, DOMNodeRemoved, DOMNodeInsertedIntoDocument, DOMNodeRemovedFromDocument, DOMAttrModified, DOMCharacterDataModified und DOMSubtreeModified.

Das Interface ergänzt Event um folgende Eigenschaften:

attrChange – Art der Attributänderung: MutationEvent.MODIFICATION (1), ADDITION (2) oder REMOVAL (3).
attrName – Name des geänderten Attributs (bei DOMAttrModified).
prevValue / newValue – alter bzw. neuer Wert des Attributs oder Textknotens.
relatedNode – betroffener Bezugsknoten, z. B. der Elternknoten bei DOMNodeInserted.

Außerdem gibt es die veraltete Methode initMutationEvent(), mit der ein über document.createEvent("MutationEvent") erzeugtes Ereignis initialisiert wurde.

Wichtig: Mutation Events gelten als veraltet. Sie bremsen DOM-Operationen stark aus, weil sie synchron während jeder Änderung feuern, und verhalten sich in den Browsern uneinheitlich. Für neuen Code sollte man immer MutationObserver verwenden. Diese Seite ist vor allem für die Pflege und Umstellung von Altcode nützlich.

Rückgabewert

Typ

MutationEvent

Beschreibung

Das Ereignisobjekt, das an Listener für Mutation Events (z. B. DOMNodeInserted) übergeben wird.

Beispiele

Altcode: auf eingefügte Knoten reagieren (mit Unterstützungsprüfung)

const liste = document.querySelector('#liste');

// Prüfen, ob der Browser Mutation Events überhaupt noch kennt
const unterstuetzt = 'MutationEvent' in window;

if (unterstuetzt) {
  const onInsert = (event) => {
    console.log('Eingefügt:', event.target.nodeName);
    console.log('Elternknoten:', event.relatedNode?.id);
  };
  liste.addEventListener('DOMNodeInserted', onInsert);

  liste.append(document.createElement('li'));

  // Listener später wieder entfernen
  liste.removeEventListener('DOMNodeInserted', onInsert);
} else {
  console.log('Mutation Events werden nicht unterstützt – MutationObserver verwenden.');
}

Eingefügt: LI Elternknoten: liste (oder in Chrome ab 127: Mutation Events werden nicht unterstützt – MutationObserver verwenden.)

Altcode: Attributänderungen mit attrChange auswerten

const box = document.querySelector('#box');
const arten = { 1: 'geändert', 2: 'hinzugefügt', 3: 'entfernt' };

box.addEventListener('DOMAttrModified', (event) => {
  console.log(
    `Attribut "${event.attrName}" ${arten[event.attrChange]}:`,
    event.prevValue, '→', event.newValue
  );
});

box.setAttribute('data-status', 'aktiv');
box.setAttribute('data-status', 'inaktiv');

Attribut "data-status" hinzugefügt: → aktiv Attribut "data-status" geändert: aktiv → inaktiv

Umstellung: dasselbe mit MutationObserver

const box = document.querySelector('#box');

const observer = new MutationObserver((mutations) => {
  for (const m of mutations) {
    if (m.type === 'attributes') {
      console.log(`Attribut "${m.attributeName}":`, m.oldValue, '→', box.getAttribute(m.attributeName));
    } else if (m.type === 'childList') {
      m.addedNodes.forEach((n) => console.log('Eingefügt:', n.nodeName));
      m.removedNodes.forEach((n) => console.log('Entfernt:', n.nodeName));
    }
  }
});

observer.observe(box, {
  attributes: true,
  attributeOldValue: true,
  childList: true,
  subtree: true
});

box.setAttribute('data-status', 'aktiv');
box.append(document.createElement('span'));

// Beobachtung beenden, wenn nicht mehr benötigt
// observer.disconnect();

Attribut "data-status": null → aktiv Eingefügt: SPAN

// Wichtig · Fallstricke

Veraltet und teils entfernt: Chrome und Edge haben Mutation Events ab Version 127 (2024) standardmäßig entfernt. Auch andere Browser-Hersteller haben die Entfernung angekündigt bzw. bereits umgesetzt. Bitte nicht mehr in neuem Code verwenden.
Performance: Die Ereignisse werden synchron bei jeder einzelnen DOM-Änderung ausgelöst. Schon ein einziger registrierter Listener kann DOM-Operationen auf der ganzen Seite deutlich verlangsamen.
Uneinheitliches Verhalten: DOMAttrModified wurde zum Beispiel in Chrome/Safari nie unterstützt. Auch die Reihenfolge und Häufigkeit von DOMSubtreeModified unterscheiden sich zwischen den Browsern.
Endlosschleifen: Wer das DOM innerhalb eines Listeners ändert, löst dadurch sofort weitere Ereignisse aus. Das kann leicht zu Rekursion oder Abstürzen führen.
Ersatz: MutationObserver sammelt Änderungen, meldet sie asynchron als Microtask und wird überall unterstützt. DOMNodeInsertedIntoDocument bzw. DOMNodeRemovedFromDocument lassen sich bei Custom Elements auch durch connectedCallback/disconnectedCallback ersetzen.

Siehe auch

MutationObserver MutationRecord Event EventTarget.addEventListener() Document.createEvent() MouseScrollEvent