DocumentFragment: Methode moveBefore()

Syntax

moveBefore(movedNode, referenceNode)

Parameter

movedNode

Ein Node, der den zu verschiebenden Knoten darstellt. Beachten Sie, dass dies ein Element- oder CharacterData-Knoten sein muss.

referenceNode

Ein Node, vor den movedNode verschoben wird, oder null. Wenn der Wert null ist, wird movedNode am Ende der Kindknoten des aufrufenden DocumentFragment eingefügt.

Rückgabewert

Keiner (undefined).

Ausnahmen

HierarchyRequestError DOMException

Wird in einer der folgenden Situationen ausgelöst:

• Das Fragment und movedNode haben unterschiedliche Shadow-inkludierende Wurzeln (die von getRootNode({ composed: true }) zurückgegebenen Wurzeln).
• Das Verschieben würde einen Knoten innerhalb seiner selbst oder eines seiner Nachfahren platzieren, auch über einen Shadow Tree hinweg.
• Der angegebene movedNode ist kein Element- oder CharacterData-Knoten.

NotFoundError DOMException

Der angegebene referenceNode ist kein Kind des DocumentFragment, auf dem Sie moveBefore() aufrufen, also des Fragments, innerhalb dessen Sie versuchen, movedNode zu verschieben.

TypeError

Das zweite Argument wurde nicht bereitgestellt.

Beschreibung

Die Methode moveBefore() verschiebt einen angegebenen Knoten an eine neue Position im DocumentFragment. Sie bietet ähnliche Funktionalität wie die Methode Node.insertBefore(), entfernt den Knoten jedoch nicht und fügt ihn anschließend wieder ein. Das bedeutet, dass der Zustand des Knotens (der beim Verschieben mit insertBefore() und ähnlichen Mechanismen zurückgesetzt würde) nach dem Verschieben erhalten bleibt. Dazu gehören:

• Der Zustand von Animationen und Übergängen.
• Der Ladezustand von <iframe>.
• Interaktivitätszustände (zum Beispiel :focus und :active).
• Der Elementzustand für Vollbild.
• Der Offen/Geschlossen-Zustand von Popovers.
• Der modale Zustand von <dialog>-Elementen (modale Dialogfelder werden nicht geschlossen).

Der Wiedergabezustand von <video>- und <audio>-Elementen ist nicht in der obigen Liste enthalten, da diese Elemente ihren Zustand beim Entfernen und erneuten Einfügen unabhängig vom verwendeten Mechanismus beibehalten.

Ein gewöhnliches DocumentFragment ist nicht verbunden. Das Anhängen an das Dokument überträgt seine Kinder und lässt das Fragment leer; das Fragment selbst wird dabei nicht verbunden. Das zustandserhaltende Verhalten ist daher bei einer verbundenen ShadowRoot, die von DocumentFragment erbt, am nützlichsten.

Wenn Änderungen am DOM mit einem MutationObserver beobachtet werden, werden mit moveBefore() verschobene Knoten mit einem entfernten Knoten und einem hinzugefügten Knoten erfasst.

Einschränkungen von moveBefore()

Bei der Verwendung von moveBefore() sind einige Einschränkungen zu beachten:

• Es funktioniert nur beim Verschieben eines Knotens innerhalb derselben Shadow-inkludierenden Wurzel. Bei einem gewöhnlichen nicht verbundenen Fragment bedeutet dies, Knoten zu verschieben, die sich bereits innerhalb dieses Fragments befinden. Bei einer verbundenen Shadow Root erfüllen Knoten, die mit demselben Dokument verbunden sind, diese Anforderung.
• Es funktioniert nicht, wenn Sie versuchen, einen Knoten, der nicht mit dem DOM verbunden ist, in ein bereits verbundenes Elternelement zu verschieben oder umgekehrt.

In solchen Fällen schlägt moveBefore() mit einer HierarchyRequestError-Ausnahme fehl. Wenn die oben genannten Einschränkungen Anforderungen für Ihren speziellen Anwendungsfall sind, sollten Sie stattdessen Node.insertBefore() verwenden oder try...catch einsetzen, um die Fehler zu behandeln, die in solchen Fällen auftreten.

Beispiele

Beibehalten des Fokus innerhalb einer Shadow Root

Dieses Beispiel zeigt, wie moveBefore() den Fokus einer Eingabe beibehält, wenn sie innerhalb einer Shadow Root verschoben wird.

HTML

Das HTML enthält ein <div> zum Hosten der Shadow Root und ein <output>, um anzuzeigen, ob die Eingabe nach jeder Verschiebung fokussiert bleibt.

<div id="host"></div>
<output id="status"></output>

JavaScript

Das Skript hängt eine Shadow Root an das <div> an und fügt ihr eine Eingabe und einen Absatz hinzu. Der keydown-Ereignis-Listener der Eingabe verwendet moveBefore(), um die Eingabe durch Übergabe von null nach den Absatz oder durch Übergabe des Absatzes als Referenzknoten davor zu verschieben. Nach jeder Verschiebung aktualisiert er die Statusausgabe dahingehend, ob die Eingabe fokussiert ist.

const shadow = document.getElementById("host").attachShadow({ mode: "open" });
const status = document.getElementById("status");
const input = document.createElement("input");
input.setAttribute("aria-label", "Type here, then press Enter to move");
input.placeholder = "Press Enter to move";
const paragraph = document.createElement("p");
paragraph.textContent = "The input can move before or after this paragraph.";
shadow.append(input, paragraph);

input.addEventListener("keydown", (event) => {
  if (event.key !== "Enter" || event.isComposing) {
    return;
  }
  event.preventDefault();
  const reference = input.nextSibling === paragraph ? null : paragraph;
  shadow.moveBefore(input, reference);
  status.textContent = `Input still focused: ${shadow.activeElement === input}`;
});

Ergebnis

Fokussieren Sie die Eingabe und drücken Sie Enter, um sie vor oder nach den Absatz zu verschieben. Die Eingabe bleibt fokussiert.

Die Verwendung von shadow.insertBefore(input, reference) würde die Eingabe stattdessen entfernen und erneut einfügen, wodurch ihr Fokus verloren ginge. Gewöhnliches erneutes Einfügen erhält den Text im Eingabefeld, jedoch nicht die anderen oben aufgeführten Zustände.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Document.moveBefore()
• Element.moveBefore()
• Node.insertBefore()