MutationEvent.initMutationEvent() — Methode · JavaScript-Referenz

Signatur

MutationEvent.prototype.initMutationEvent(type, canBubble, cancelable, relatedNode, prevValue, newValue, attrName, attrChange)

Beschreibung

Die Methode initMutationEvent() legt die Eigenschaften eines MutationEvent-Objekts fest, das zuvor mit document.createEvent("MutationEvent") erzeugt wurde. Dazu gehören der Ereignistyp (z. B. "DOMAttrModified"), ob das Ereignis im DOM nach oben weitergereicht wird und abbrechbar ist, sowie die mutationsspezifischen Felder relatedNode, prevValue, newValue, attrName und attrChange.

Die Methode muss vor dem Auslösen mit dispatchEvent() aufgerufen werden. Ruft man sie auf, während das Ereignis schon ausgelöst wird, hat das keine Wirkung. Mutationsereignisse, die man selbst auslöst, sind synthetisch. Der Browser prüft also nicht, ob die angegebene Änderung am DOM wirklich stattgefunden hat.

Mutation Events gehören zum Altbestand der Webplattform. Sie gelten als langsam und fehleranfällig und sind in der aktuellen DOM-Spezifikation nicht mehr enthalten. Neuer Code sollte stattdessen MutationObserver verwenden, um DOM-Änderungen zu beobachten. Für eigene Ereignisse ist new CustomEvent() das Mittel der Wahl. initMutationEvent() ist heute vor allem für die Pflege alter Codebasen und für Tests von Altcode interessant.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Das Ereignisobjekt wird direkt verändert.

Beispiele

Synthetisches DOMAttrModified-Ereignis erzeugen und auslösen

const box = document.createElement('div');
document.body.append(box);

box.addEventListener('DOMAttrModified', (e) => {
  console.log(`${e.attrName}: "${e.prevValue}" → "${e.newValue}" (Art ${e.attrChange})`);
});

try {
  const evt = document.createEvent('MutationEvent');
  evt.initMutationEvent(
    'DOMAttrModified', // type
    true,              // canBubble
    false,             // cancelable
    null,              // relatedNode
    'klein',           // prevValue
    'gross',           // newValue
    'data-size',       // attrName
    MutationEvent.MODIFICATION // attrChange (1)
  );
  box.dispatchEvent(evt);
} catch (err) {
  console.warn('MutationEvent wird nicht unterstützt:', err.name);
}

data-size: "klein" → "gross" (Art 1) // oder in Browsern ohne Unterstützung: // MutationEvent wird nicht unterstützt: NotSupportedError

Hilfsfunktion mit Funktionsprüfung für Altcode-Tests

const fireNodeInserted = (target, parent) => {
  if (typeof MutationEvent === 'undefined' ||
      typeof MutationEvent.prototype.initMutationEvent !== 'function') {
    return false; // Kein Support: Test überspringen
  }
  const evt = document.createEvent('MutationEvent');
  evt.initMutationEvent('DOMNodeInserted', true, false, parent, '', '', '', 0);
  return target.dispatchEvent(evt);
};

const list = document.createElement('ul');
const item = document.createElement('li');
list.append(item);

list.addEventListener('DOMNodeInserted', (e) => {
  console.log('Eingefügt in:', e.relatedNode.nodeName);
});

console.log('Ausgelöst:', fireNodeInserted(item, list));

Eingefügt in: UL Ausgelöst: true // ohne Unterstützung: Ausgelöst: false

Moderne Alternative: MutationObserver statt Mutation Events

const target = document.createElement('div');
document.body.append(target);

const observer = new MutationObserver((records) => {
  for (const r of records) {
    if (r.type === 'attributes') {
      console.log(`${r.attributeName}: "${r.oldValue}" → "${target.getAttribute(r.attributeName)}"`);
    }
  }
});

observer.observe(target, { attributes: true, attributeOldValue: true });

target.setAttribute('data-size', 'klein');
target.setAttribute('data-size', 'gross');

data-size: "null" → "gross" data-size: "klein" → "gross"

// Wichtig · Fallstricke

Veraltet: Mutation Events wurden aus der DOM-Spezifikation entfernt. Chromium-basierte Browser (Chrome, Edge) unterstützen sie ab Version 127 nicht mehr, und auch andere Browser bauen die Unterstützung ab. document.createEvent("MutationEvent") kann deshalb einen NotSupportedError auslösen. Prüfe vor der Nutzung, ob die Funktion vorhanden ist, oder fange den Fehler mit try/catch ab.
Keine echte Änderung am DOM: Das Auslösen eines selbst erzeugten Ereignisses verändert das DOM nicht. Es ruft nur die registrierten Listener auf. Außerdem ist event.isTrusted dabei false.
Zeitpunkt: Der Aufruf während eines laufenden dispatchEvent() wird ignoriert. Initialisiere das Ereignis also immer vorher.
Kein Konstruktor: Anders als bei modernen Ereignissen gibt es kein new MutationEvent(). Der Weg über createEvent() und initMutationEvent() ist der einzige.
Leistung: Echte Mutation Events werden synchron bei jeder DOM-Änderung ausgelöst und bremsen die Seite spürbar. MutationObserver sammelt Änderungen dagegen und meldet sie asynchron als Microtask.

Siehe auch

CustomEvent.initCustomEvent() CompositionEvent.initCompositionEvent() TimeEvent.initTimeEvent() UIEvent.initUIEvent() MouseEvent.initMouseEvent() KeyboardEvent.initKeyboardEvent() new SecurityPolicyViolationEvent()