MutationEvent.relatedNode — Eigenschaft · JavaScript-Referenz

Signatur

MutationEvent.relatedNode

Beschreibung

Die schreibgeschützte Eigenschaft relatedNode des MutationEvent-Interfaces liefert einen zweiten Knoten, der an der DOM-Änderung beteiligt ist. Das ist nicht der Knoten, der sich geändert hat (der steht in event.target), sondern ein zugehöriger Kontextknoten. Anders als die MDN-Kurzbeschreibung nahelegt, ist der Wert kein String, sondern ein Node oder null.

Was genau drinsteht, hängt vom Ereignistyp ab:

DOMNodeInserted / DOMNodeRemoved: der Elternknoten, in den eingefügt bzw. aus dem entfernt wurde.
DOMAttrModified: der betroffene Attr-Knoten.
DOMSubtreeModified, DOMCharacterDataModified, DOMNodeInsertedIntoDocument, DOMNodeRemovedFromDocument: in der Regel null.

Mutation Events sind veraltet. Sie werden synchron bei jeder einzelnen DOM-Änderung ausgelöst, bremsen dadurch die Leistung stark und sind deshalb aus mehreren Browsern entfernt worden. Für neuen Code nimmt man den MutationObserver. Bei ihm entspricht MutationRecord.target dem früheren relatedNode von Einfüge- und Entfern-Ereignissen: Es ist der Elternknoten, dessen childList sich geändert hat.

Rückgabewert

Typ

Node | null

Beschreibung

Der mit der Änderung verbundene Knoten: der Elternknoten bei DOMNodeInserted/DOMNodeRemoved, der Attr-Knoten bei DOMAttrModified, sonst meist null.

Beispiele

Elternknoten beim Einfügen ermitteln (alter Code)

const list = document.createElement('ul');
list.id = 'todo';
document.body.append(list);

const onInsert = (event) => {
  // event.target = eingefügter Knoten, relatedNode = Elternknoten
  console.log('Eingefügt:', event.target.nodeName);
  console.log('In:', event.relatedNode?.id);
};

list.addEventListener('DOMNodeInserted', onInsert);
list.append(document.createElement('li'));

// Listener später wieder entfernen
list.removeEventListener('DOMNodeInserted', onInsert);

Eingefügt: LI In: todo (Nur in Browsern, die Mutation Events noch unterstützen – sonst keine Ausgabe.)

Geändertes Attribut über relatedNode auslesen

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

box.addEventListener('DOMAttrModified', (event) => {
  const attr = event.relatedNode; // Attr-Knoten
  console.log(`${attr?.name}: ${event.prevValue} -> ${event.newValue}`);
});

box.setAttribute('data-state', 'open');

data-state: -> open (Nur in Browsern mit Unterstützung für DOMAttrModified.)

Moderner Ersatz mit MutationObserver

const list = document.createElement('ul');
list.id = 'todo';
document.body.append(list);

const observer = new MutationObserver((records) => {
  for (const record of records) {
    // record.target entspricht dem früheren relatedNode
    for (const node of record.addedNodes) {
      console.log(`Eingefügt: ${node.nodeName} in #${record.target.id}`);
    }
  }
});

observer.observe(list, { childList: true });
list.append(document.createElement('li'));

// Aufräumen, wenn nicht mehr benötigt
setTimeout(() => observer.disconnect(), 0);

Eingefügt: LI in #todo

// Wichtig · Fallstricke

Veraltet und entfernt: Chrome und Edge haben Mutation Events ab Version 127 standardmäßig entfernt. Auch andere Browser bauen sie ab. Code, der sich auf relatedNode verlässt, bekommt dort einfach keine Ereignisse mehr, und zwar ohne Fehlermeldung.
Typ: Der Wert ist ein Node oder null, kein String. Deshalb vor dem Zugriff prüfen, z. B. mit event.relatedNode?.nodeName.
Verwechslungsgefahr: event.target ist der geänderte Knoten, relatedNode ist der Kontextknoten (Elternknoten oder Attribut).
Leistung: Mutation Events werden synchron und bei jeder Änderung ausgelöst. Große DOM-Operationen werden dadurch deutlich langsamer. MutationObserver sammelt die Änderungen und liefert sie gebündelt und asynchron.
Es gibt keine verlässliche Funktionserkennung für einzelne Mutation Events. Am besten stellt man komplett auf MutationObserver um, der in allen modernen Browsern verfügbar ist.

Siehe auch

ImageTrackList.selectedIndex MutationEvent.attrName MutationEvent.attrChange MutationEvent.newValue MutationEvent.prevValue