Document.moveBefore() — Methode · JavaScript-Referenz

Signatur

Document.prototype.moveBefore(movedNode, referenceNode)

Beschreibung

moveBefore() macht dasselbe wie insertBefore(), aber als atomare Verschiebung statt als „Entfernen und neu Einfügen“. Der Knoten wird dabei nicht aus dem DOM gelöst. Deshalb bleiben Zustände erhalten, die beim klassischen Einfügen verloren gehen würden: laufende CSS-Animationen und -Übergänge, geladene <iframe>-Inhalte, Fokus, Wiedergabe von <video>, offene popover- und <dialog>-Elemente. Custom Elements bekommen statt disconnectedCallback/connectedCallback den connectedMoveCallback, sofern er definiert ist.

Die Variante an Document arbeitet nur mit den direkten Kindern des Dokuments. Dort dürfen nur wenige Knotenarten stehen: das Wurzelelement (<html>), die Doctype-Deklaration, Kommentare und Processing Instructions. In der Praxis verschiebt man damit also vor allem Kommentare oder Processing Instructions vor oder hinter das documentElement. Die meisten Anwendungen brauchen eher Element.prototype.moveBefore() oder DocumentFragment.prototype.moveBefore(), die genauso funktionieren.

Der verschobene Knoten muss ein Element oder ein CharacterData-Knoten sein (zum Beispiel Comment). Er muss dieselbe Wurzel haben wie das Ziel, also schon im selben Dokument hängen. Knoten aus einem anderen Dokument oder abgelöste Knoten lassen sich nicht in ein eingehängtes Dokument verschieben. Dafür braucht man weiterhin insertBefore() oder append().

Parameter

Name	Typ	Default	Beschreibung
$movedNode Pflicht	Element \| CharacterData		Der Knoten, der verschoben wird. Er muss sich schon im selben Dokument befinden (gleiche Wurzel, auch innerhalb von Shadow DOM).
$referenceNode Pflicht	Node \| null		Ein direktes Kind von `document`, vor das `movedNode` gesetzt wird. Bei `null` wird der Knoten als letztes Kind eingefügt. Das Argument muss immer angegeben werden, auch wenn es `null` ist.

Rückgabewert

Typ

undefined

Beschreibung

Gibt nichts zurück (anders als insertBefore(), das den eingefügten Knoten zurückgibt).

Beispiele

Kommentar vor das html-Element verschieben

// Kommentar steht zunächst am Ende des Dokuments
const hinweis = document.createComment(' Build: 2024-06-01 ');
document.append(hinweis);

// Atomar vor das Wurzelelement verschieben
document.moveBefore(hinweis, document.documentElement);

console.log(document.documentElement.previousSibling === hinweis);

true

Mit null ans Ende verschieben

const kommentar = document.createComment(' Lizenzhinweis ');
document.insertBefore(kommentar, document.documentElement);

// referenceNode = null → als letztes Kind von document
document.moveBefore(kommentar, null);

console.log(document.lastChild === kommentar);

true

Funktionsprüfung mit Rückfall auf insertBefore()

const verschiebeVor = (parent, node, ref) => {
  if ('moveBefore' in parent && node.isConnected === parent.isConnected) {
    try {
      parent.moveBefore(node, ref);
      return 'moveBefore';
    } catch (err) {
      // HierarchyRequestError, z. B. bei anderem Dokument
      console.warn(err.name);
    }
  }
  parent.insertBefore(node, ref);
  return 'insertBefore';
};

const c = document.createComment(' Marker ');
document.append(c);
console.log(verschiebeVor(document, c, document.documentElement));

moveBefore (in Browsern mit Unterstützung, sonst: insertBefore)

Fehler bei ungültigem Referenzknoten

const c = document.createComment(' Test ');
document.append(c);

try {
  // document.body ist kein direktes Kind von document
  document.moveBefore(c, document.body);
} catch (err) {
  console.log(err.name);
}

NotFoundError

// Wichtig · Fallstricke

Ausnahmen: HierarchyRequestError tritt auf, wenn movedNode kein Element/CharacterData ist (etwa ein DocumentType), wenn er eine andere Wurzel hat oder wenn das Ergebnis ungültig wäre. Beispiele dafür sind ein Text-Knoten direkt unter document oder ein zweites Wurzelelement. NotFoundError tritt auf, wenn referenceNode kein direktes Kind von document ist.
Nur für Knoten im selben Dokument: Neu erstellte, noch nicht eingehängte Knoten oder Knoten aus einem anderen Dokument (etwa aus einem iframe) lassen sich damit nicht in das Dokument verschieben. Dafür insertBefore() oder adoptNode() verwenden.
Anders als insertBefore(): Das zweite Argument ist Pflicht, und es gibt keinen Rückgabewert.
Begrenzter Nutzen an Document: Weil direkt unter dem Dokument nur Wurzelelement, Doctype, Kommentare und Processing Instructions stehen dürfen, ist die Methode meist erst an Element interessant (zum Beispiel beim Umsortieren von Listen, ohne dass iframes neu laden).
Browser-Kompatibilität: Die Methode ist neu (Chromium 133+, Firefox 144+) und in Safari noch nicht verfügbar. Deshalb vorher mit 'moveBefore' in document prüfen und einen Rückfall vorsehen.
Mutation Observer melden die Verschiebung wie bisher als Entfernen und Hinzufügen in einem childList-Eintrag.

Siehe auch

Element.moveBefore() DocumentFragment.moveBefore() Node.insertBefore() Document.adoptNode() Element.before() Document.documentElement MutationObserver