Node: replaceChild() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die replaceChild() Methode der Node-Schnittstelle ersetzt ein Kindknoten innerhalb des angegebenen (Eltern-)Knotens.

Syntax

js
replaceChild(newChild, oldChild)

Parameter

newChild

Der neue Knoten, der oldChild ersetzen soll.

Warnung: Wenn sich der neue Knoten bereits an einer anderen Stelle im DOM befindet, wird er zuerst von dieser Position entfernt.

oldChild

Das zu ersetzende Kind.

Hinweis: Die Reihenfolge der Parameter, neu vor alt, ist ungewöhnlich. Element.replaceWith(), das nur auf Knoten angewendet wird, die Elemente sind, könnte leichter zu lesen und zu verwenden sein.

Rückgabewert

Der ersetzte Node. Dies ist derselbe Knoten wie oldChild.

Ausnahmen

HierarchyRequestError DOMException

Wird ausgelöst, wenn die Beschränkungen des DOM-Baums verletzt werden, das heißt, wenn einer der folgenden Fälle eintritt:

  • Wenn das Elternteil von oldChild nicht ein Document, DocumentFragment oder ein Element ist.
  • Wenn der Austausch von oldChild durch newChild zu einem Zyklus führen würde, das heißt, wenn newChild ein Vorfahre des Knotens ist.
  • Wenn newChild kein DocumentFragment, ein DocumentType, ein Element oder ein CharacterData ist.
  • Wenn der aktuelle Knoten ein Text ist und sein Elternteil ein Document ist.
  • Wenn der aktuelle Knoten ein DocumentType ist und sein Elternteil nicht ein Document ist, da ein doctype immer ein direkter Nachfahre eines Dokuments sein sollte.
  • Wenn das Elternteil des Knotens ein Document ist und newChild ein DocumentFragment mit mehr als einem Element-Kind ist, oder das einen Text-Kind hat.
  • Wenn der Austausch von oldChild durch newChild zu einem Document mit mehr als einem Element als Kind führen würde.
  • Wenn der Austausch von oldChild durch newChild zur Anwesenheit eines Element-Knotens vor einem DocumentType-Knoten führen würde.
NotFoundError DOMException

Wird ausgelöst, wenn das Elternteil von oldChild nicht der aktuelle Knoten ist.

Beispiel

js
// Given:
// <div>
//  <span id="childSpan">foo bar</span>
// </div>

// Create an empty element node
// without an ID, any attributes, or any content
const sp1 = document.createElement("span");

// Give it an id attribute called 'newSpan'
sp1.id = "newSpan";

// Create some content for the new element.
const sp1_content = document.createTextNode("new replacement span element.");

// Apply that content to the new element
sp1.appendChild(sp1_content);

// Build a reference to the existing node to be replaced
const sp2 = document.getElementById("childSpan");
const parentDiv = sp2.parentNode;

// Replace existing node sp2 with the new span element sp1
parentDiv.replaceChild(sp1, sp2);

// Result:
// <div>
//   <span id="newSpan">new replacement span element.</span>
// </div>

Spezifikationen

Specification
DOM Standard
# dom-node-replacechild

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch