12k
All articles

DOM-Knoten verschieben, ohne den Zustand zu verlieren

Erfahren Sie, wie Element.moveBefore() beim Verschieben von DOM-Knoten den Zustand von Iframes, Fokus, Animationen und Dialogen erhält – inklusive Syntax und Fallbacks.

OpenReplay Team
OpenReplay Team
DOM-Knoten verschieben, ohne den Zustand zu verlieren

Element.moveBefore() verschiebt einen Knoten, der sich bereits im Dokument befindet, ohne den Schritt aus Entfernen und erneutem Einfügen, den appendChild() und insertBefore() ausführen. Dadurch behält ein <iframe> seine geladene Seite, ein fokussiertes Eingabefeld seinen Fokus und eine laufende CSS-Animation läuft einfach weiter.

Die meisten Entwickler, die Live-Elemente in einen anderen Elternknoten umhängen, kennen das Problem: Sie ziehen eine Karte in eine neue Spalte, und der eingebettete Player darin wird leer und lädt neu. Oder das Feld, in das Sie gerade tippen, verliert mitten im Wort den Fokus.

Chrome hat moveBefore() mit Chrome 133 ausgeliefert, und die Funktion taucht in den Release Notes zu Chrome 133 als „DOM state-preserving move“ auf. Dieser Artikel behandelt die Syntax, eine Demo, die genaue Liste der erhaltenen Zustände, die Fehlerfälle, Hooks für Custom Elements und einen sicheren Fallback. Wenn Sie zuerst die Grundlagen auffrischen möchten, lesen Sie Working with the DOM in JavaScript und The life cycle of DOM elements.

Die wichtigsten Punkte

  • parent.moveBefore(node, ref) nimmt dieselben Argumente wie insertBefore() entgegen, verschiebt den Knoten aber, ohne ihn zu entfernen und neu einzufügen. So behalten iframes, Fokus, Animationen, Popover und modale Dialoge ihren Zustand.
  • Der verschobene Knoten muss ein Element- oder CharacterData-Knoten sein. Verschiebungen zwischen Dokumenten, zwischen verbundenen und nicht verbundenen Bäumen oder in einen eigenen Nachfahren des Knotens lösen einen HierarchyRequestError aus.
  • Ein MutationObserver registriert eine Verschiebung mit moveBefore() weiterhin als eine Entfernung und ein Hinzufügen.
  • Custom Elements, die connectedMoveCallback() definieren, erhalten diesen Callback anstelle von disconnectedCallback() und connectedCallback().
  • Safari unterstützt moveBefore() nicht. Prüfen Sie daher 'moveBefore' in Element.prototype und greifen Sie andernfalls auf insertBefore() zurück.

Warum setzen appendChild und insertBefore den Zustand zurück?

Jede Verschiebung mit appendChild() oder insertBefore() besteht eigentlich aus zwei Operationen: Der Browser entfernt den Knoten aus dem Dokument und fügt ihn anschließend wieder ein. Das Chrome-Team weist in seinem Launch-Beitrag darauf hin, dass es im DOM seit den frühen Standards keine andere Möglichkeit gab, einen Knoten zu verschieben. Beim Entfernen eines Knotens wird jeglicher Zustand abgebaut, der nur existiert, solange der Knoten verbunden ist. Ein iframe entlädt sein Dokument und lädt es neu, ein fokussiertes Element verliert den Fokus, CSS-Animationen beginnen von vorn, und geöffnete Popover sowie modale Dialoge werden geschlossen.

In Session-Replays von Dashboards mit umsortierbaren Elementen zeigt sich der Fehler meist so: Ein Benutzer zieht eine Karte, tippt weiter, und die Tastenanschläge kommen nicht an, weil das Feld den Fokus verloren hat. Eingebettete iframes laden mitten in der Sitzung sichtbar neu.

Syntax von moveBefore()

moveBefore() nimmt dieselben zwei Argumente wie insertBefore() entgegen: den zu verschiebenden Knoten und einen Referenzknoten. Wird null als Referenz übergeben, wird der Knoten ans Ende der Kindknoten des Elternelements verschoben.

parent.moveBefore(movedNode, referenceNode);
parent.moveBefore(movedNode, null); // append

Laut der MDN-Referenz zu moveBefore() muss der verschobene Knoten ein Element- oder ein CharacterData-Knoten sein. Textknoten sind zulässig, Dokumenttypen beispielsweise nicht. Die Methode existiert außerdem auf Document und DocumentFragment. Sie können also Knoten innerhalb eines Fragments verschieben, obwohl ein Fragment nie mit dem Dokument verbunden ist. Die Methode ist im DOM Living Standard definiert.

Demo: Ein iframe mit und ohne moveBefore verschieben

Am schnellsten lässt sich der Unterschied mit einem iframe zeigen, das einen eigenen internen Zustand hat. Diese Demo verwendet srcdoc und löst daher keine Netzwerkanfrage aus.

<div id="left" class="box">
  <iframe id="frame" srcdoc="<button onclick='this.textContent=++n'>0</button><script>let n=0</script>"></iframe>
</div>
<div id="right" class="box"></div>
<button id="viaInsert">Move with insertBefore()</button>
<button id="viaMove">Move with moveBefore()</button>
<script>
  const frame = document.getElementById('frame');
  const left = document.getElementById('left');
  const right = document.getElementById('right');
  const target = () => (frame.parentElement === left ? right : left);

  document.getElementById('viaInsert').onclick = () =>
    target().insertBefore(frame, null); // iframe reloads, counter back to 0

  document.getElementById('viaMove').onclick = () =>
    target().moveBefore(frame, null);   // counter value survives
</script>

Klicken Sie einige Male auf den Zähler im Frame und probieren Sie dann beide Buttons aus. insertBefore() lädt den Frame neu, und der Zähler springt auf null zurück. moveBefore() behält den Zählerstand bei. Der zweite Button funktioniert nur in einem Browser, der die Methode unterstützt (siehe den Abschnitt zur Feature-Erkennung weiter unten).

Beim Fokus verhält es sich genauso:

const input = document.querySelector('#note');
input.focus();
sidebar.moveBefore(input, null);
console.log(document.activeElement === input); // true
// With sidebar.insertBefore(input, null), focus is lost

Welchen Zustand erhält moveBefore()?

moveBefore() erhält eine bestimmte, auf MDN aufgeführte Menge an Zuständen – nicht jeden denkbaren Zustand:

  • Animations- und Transition-Zustand
  • Ladezustand von <iframe>
  • :focus und :active
  • Fullscreen-Zustand eines Elements
  • Geöffneter Zustand von Popovern
  • Zustand modaler <dialog>-Elemente

Native <video>- und <audio>-Elemente behalten ihren Wiedergabezustand auch dann, wenn sie mit appendChild() oder insertBefore() verschoben werden. Bei Medien spielt moveBefore() daher eine Rolle, wenn der Player in ein <iframe> eingebettet ist, etwa bei einem Video-Embed eines Drittanbieters, nicht jedoch bei nativen Medienelementen.

Fehler und Einschränkungen von moveBefore()

moveBefore() ist strenger als insertBefore(). Die Methode wirft in Fällen einen Fehler, in denen insertBefore() stillschweigend ein Entfernen und Einfügen durchführen würde.

FehlerAusgelöst, wennVorgehen
HierarchyRequestErrorVerschiebung zwischen einem verbundenen und einem nicht verbundenen BauminsertBefore() verwenden
HierarchyRequestErrorVerschiebung zwischen DokumenteninsertBefore() verwenden (oder zuvor adoptNode())
HierarchyRequestErrorEin Knoten wird in einen eigenen Nachfahren verschobenZiel korrigieren: Hier liegt ein Logikfehler vor
HierarchyRequestErrormovedNode ist kein Element- oder CharacterData-KnoteninsertBefore() verwenden
NotFoundErrorreferenceNode ist kein Kindknoten des ElternelementsEinen tatsächlichen Kindknoten oder null übergeben
TypeErrorDas zweite Argument fehltZum Anhängen explizit null übergeben

Die Zeile mit dem TypeError sorgt oft für Überraschungen, weil man Gewohnheiten von insertBefore() übernimmt: Ein Aufruf von moveBefore(node) mit nur einem Argument hängt den Knoten nicht an.

MutationObserver und connectedMoveCallback

Ein MutationObserver erfasst einen mit moveBefore() verschobenen Knoten weiterhin als einen entfernten und einen hinzugefügten Knoten. Bestehende Observer erhalten also auch bei Verschiebungen weiterhin Records. Die Move-Schritte des DOM-Standards reihen einen Removal-Record für das alte Elternelement und einen Addition-Record für das neue ein. Code, der eine Entfernung als „zerstört“ interpretiert, benötigt ein anderes Signal, wenn er Verschiebungen von Löschungen unterscheiden soll. Zur Einrichtung von Observern siehe The three DOM observer APIs.

Custom Elements erhalten einen eigenen Hook für Verschiebungen: connectedMoveCallback(). Wie der MDN-Leitfaden zu Custom Elements erklärt, wird connectedMoveCallback(), sofern definiert, anstelle von connectedCallback() und disconnectedCallback() aufgerufen, wann immer das Element über Element.moveBefore() an eine andere Stelle im DOM verschoben wird.

class DashCard extends HTMLElement {
  connectedCallback()     { /* initial setup: subscriptions, timers */ }
  disconnectedCallback()  { /* teardown */ }
  connectedMoveCallback() { /* runs instead of the two above on moveBefore() */ }
}
customElements.define('dash-card', DashCard);

Definiert die Klasse kein connectedMoveCallback(), führt eine Verschiebung mit moveBefore() weiterhin zuerst disconnectedCallback() und dann connectedCallback() aus. Wird die Methode definiert, und sei es nur als leere Funktion, ersetzt sie dieses Paar. Die HTML-Spezifikation beschreibt dieses Verhalten.

Feature-Erkennung und Fallback für moveBefore

Prüfen Sie 'moveBefore' in Element.prototype, bevor Sie die Methode aufrufen. Greifen Sie auf insertBefore() zurück, wenn die Methode fehlt, und ebenso, wenn sie bei einer Verschiebung, die insertBefore() akzeptieren würde, einen HierarchyRequestError wirft. Laut caniuse wird die Methode von Chrome und Edge ab Version 133 sowie von Firefox ab Version 144 unterstützt, von Safari jedoch nicht. web-features führt sie als „Limited availability“ und nicht als „Baseline“.

function moveNode(parent, node, ref = null) {
  if ('moveBefore' in Element.prototype) {
    try {
      parent.moveBefore(node, ref);
      return;
    } catch (err) {
      if (err.name !== 'HierarchyRequestError') throw err; // NotFoundError etc. are real bugs
    }
  }
  const active = document.activeElement;
  parent.insertBefore(node, ref); // state-resetting path
  if (active && node.contains(active)) active.focus();
}

Der Fallback über insertBefore() lädt iframes weiterhin neu, startet Animationen neu und schließt Dialoge – genau so, wie es insertBefore() schon immer getan hat. Das Wiederherstellen des Fokus setzt lediglich den Fokus zurück; die Cursorposition ist nicht garantiert. Diese Prüfung deckt nur Element-Elternknoten ab. Sie verrät nicht, ob Document oder DocumentFragment die Methode unterstützen.

Fazit

Mit moveBefore() erhält das DOM erstmals eine echte Verschiebeoperation: ein einziger Aufruf, der iframes geladen, den Fokus an Ort und Stelle und Animationen am Laufen hält, solange Sie sich innerhalb der auf MDN aufgeführten Einschränkungen bewegen. Suchen Sie in Ihrem Drag-and-Drop- oder Morphing-Code nach allen Aufrufen von appendChild() oder insertBefore(), die einen Live-Knoten verschieben, leiten Sie diese über einen Helfer wie moveNode() und ergänzen Sie connectedMoveCallback() bei jedem Custom Element, dessen Setup beim Neupositionieren nicht erneut ausgeführt werden soll.

FAQs

Kann moveBefore() ein Element in einen Shadow Root hinein oder aus ihm heraus verschieben?

Ja. ShadowRoot erbt von DocumentFragment und verfügt daher über eine eigene moveBefore()-Methode. Die Verschiebung muss innerhalb desselben Shadow-including Root bleiben, und ein verbundener Shadow Root erfüllt diese Anforderung für jeden Knoten, der mit demselben Dokument verbunden ist. Wird Light-DOM-Inhalt in einen verbundenen Shadow Tree verschoben, bleiben Fokus, iframe-Ladezustand und die übrigen auf MDN aufgeführten Zustände erhalten.

Warum wirft moveBefore() einen Fehler, wenn ich ein neu erstelltes Element einfüge?

Ein mit document.createElement() erzeugtes Element ist noch nicht mit dem Dokument verbunden. Wird ein nicht verbundener Knoten in ein verbundenes Elternelement verschoben, wird ein HierarchyRequestError ausgelöst. Verwenden Sie für das erstmalige Einfügen appendChild() oder insertBefore(). Ein Knoten, der noch nie verbunden war, hat keinen iframe-, Fokus- oder Animationszustand, der erhalten werden müsste, sodass nichts verloren geht. Setzen Sie moveBefore() erst für alle späteren Verschiebungen ein.

Lässt sich moveBefore() für Safari polyfillen?

Nein. Ein Polyfill kann zwar eine moveBefore()-Methode hinzufügen, die insertBefore() aufruft, übernimmt damit aber nur den Methodennamen. Die Browser-Engine hält iframe-Dokumente, Fokus, Animationen und geöffnete Popover während der Verschiebung am Leben, und das kann JavaScript nicht leisten. In Browsern ohne native Unterstützung verhält sich ein Shim exakt wie insertBefore() und setzt denselben Zustand zurück.

Verwenden bereits Bibliotheken moveBefore()?

Ja. htmx hat die Unterstützung für moveBefore() in Version 2.0.3 eingeführt, die im Oktober 2024 erschienen ist. Stellt der Browser moveBefore() bereit, nutzt htmx die Methode, um mit hx-preserve markierte Elemente beim Austausch von Inhalten zu verschieben, sodass diese Elemente ihren Zustand behalten. In Browsern ohne die Methode kehrt htmx zu seinem normalen Verhalten zurück und verschiebt Elemente auf die herkömmliche Weise durch Entfernen und Einfügen.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.