jQuery / Methode / .replaceWith() - Ganze Elemente ersetzen
jQuerys .replaceWith(neuerInhalt) ersetzt die ausgewählten Elemente selbst. Zurückgegeben wird das jQuery-Objekt der entfernten ursprünglichen Elemente, nicht der neu eingefügten. Speichern Sie eine neue Referenz oder wählen Sie die neuen Elemente anschließend erneut aus dem Dokument.
Ganzes Element oder innerer Inhalt
.replaceWith() entfernt bestehende Knoten samt Kindern aus dem Document Object Model (DOM) und setzt neue Inhalte an ihre Stelle. $(".entry").replaceWith("<section>New</section>") ersetzt äußeres Tag, Klassen und Kinder von .entry. Die neue section übernimmt .entry nicht automatisch.
Für einen erhaltenen äußeren Knoten mit geändertem Inhalt verwenden Sie .html(). replaceWith akzeptiert HTML-Strings, DOM-Elemente, Elementarrays, jQuery-Objekte oder eine Funktion mit Ersatzinhalt als Rückgabe. In der Funktion lesen Sie jedes alte Element über this und übertragen benötigte Werte ausdrücklich.
Vollständiges Beispiel mit Eingaben und Ereignissen
Speichern Sie alles in UTF-8 als replace-demo.html und öffnen Sie die Datei im Browser. Für die offizielle jQuery-Datei 4.0.0 vom Content Delivery Network (CDN) benötigen Sie Internet, keine Installation. Ersetzung, Eingaben, Ereignisse, Reset und Konsolencode wurden mit 3.7.1 und 4.0.0 ausgeführt.
Zwei div.entry werden zu section.entry. Namen werden mit .text(), aktuelle Eingabewerte mit .val() übertragen. Die ursprünglichen Buttons erhalten direkte Handler; ein weiterer Handler wird vom erhaltenen #board delegiert.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Replace whole elements</title>
<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<style>
body { font: 16px/1.6 sans-serif; max-width: 760px; margin: 24px auto; padding: 16px; }
button, input { font: inherit; margin: 4px; max-width: 100%; box-sizing: border-box; }
.entry { padding: 12px; border: 1px solid #aab; margin: 10px 0; }
section.entry { border: 2px solid teal; background: #edf9f6; }
pre { white-space: pre-wrap; overflow-wrap: anywhere; }
</style>
</head>
<body>
<h1>Replace the outer element</h1>
<button type="button" id="replace">Replace both entries</button>
<button type="button" id="reset">Reset</button>
<div id="board">
<div class="entry"><strong class="name">Alpha</strong><input aria-label="Alpha note" value="First note"><button type="button" class="inspect">Inspect</button></div>
<div class="entry"><strong class="name">Beta</strong><input aria-label="Beta note" value="Second note"><button type="button" class="inspect">Inspect</button></div>
</div>
<pre id="result" aria-live="polite"></pre>
<script>
$(function () {
const initial = $("#board").html();
let $old, $returned = null, direct = 0, delegated = 0;
function report() {
const tags = $("#board > .entry").map(function () { return this.tagName.toLowerCase(); }).get();
const connected = $old.filter(function () { return this.isConnected; }).length;
$("#result").text(`live tags=${tags.join(",")}\noriginal connected=${connected}\nreturned original=${$returned ? $returned === $old : "(not run)"}\nold data=${$old.first().data("lesson")}\ndirect=${direct}; delegated=${delegated}`);
}
function initialize() {
$old = $("#board > .entry").data("lesson", "original");
$old.find(".inspect").on("click.directExample", function () { direct++; });
$returned = null; direct = 0; delegated = 0;
$("#replace").prop("disabled", false);
report();
}
$("#board").on("click.replaceLesson", ".inspect", function () { delegated++; report(); });
$("#replace").on("click", function () {
$returned = $old.replaceWith(function () {
const name = $(this).find(".name").text();
const note = $(this).find("input").val();
return $("<section>", { "class": "entry" }).append(
$("<strong>", { "class": "name" }).text(name),
$("<input>", { "aria-label": name + " note" }).val(note),
$("<button>", { type: "button", "class": "inspect" }).text("Inspect")
);
});
$returned.addClass("old-only");
$(this).prop("disabled", true);
report();
});
$("#reset").on("click", function () { $("#board").html(initial); initialize(); });
initialize();
});
</script>
</body>
</html>Anfangsausgabe: original connected zählt ursprüngliche Elemente, die noch mit dem Dokument verbunden sind. old data zeigt darauf gespeicherte jQuery-Daten.
live tags=div,div
original connected=2
returned original=(not run)
old data=original
direct=0; delegated=0- Drücken Sie vor dem Ersetzen einmal Inspect: direct=1; delegated=1. Beide Handler laufen.
- Ändern Sie Alphas Eingabe und drücken Sie Replace both entries. live tags wird section,section, original connected wird 0, returned original true und old data undefined. Der bearbeitete Wert bleibt dank ausdrücklicher Kopie in das neue input erhalten.
- Danach erhöht Inspect nur delegated. Der neue Button ist ein anderer Knoten ohne geerbten direkten Handler.
- $returned.addClass("old-only") verändert entfernte Knoten. Neue sections im Dokument erhalten diese Klasse nicht. Prüfen Sie das auch in den Entwicklerwerkzeugen.
- Nach einmaligem Ersetzen wird der Ersetzen-Button deaktiviert. Reset stellt HTML, Werte und Zähler wieder her und bindet direkte Handler neu. Die Delegation bleibt einmalig auf #board, ohne Duplikate bei wiederholtem Reset.
Eingaben, Daten und Fokus werden nicht automatisch übertragen. Das Beispiel kopiert aktuelle value-Werte, stellt den Fokus aber nicht wieder her. Soll eine Eingabe fortgesetzt werden, speichern Sie das neue Steuerelement und planen nötige Fokusbewegungen separat.
Rückgaben und vorhandene Knoten
Halten Sie ein neues jQuery-Objekt als $new fest, bevor Sie es replaceWith übergeben. Führen Sie den folgenden Code in derselben Seitenkonsole aus. Temporäre Container werden erstellt und entfernt; die beiden Hauptkarten bleiben erhalten. .replaceAll() schreibt die Operation vom neuen Inhalt zum Ziel und liefert die eingefügte Menge.
const $holder = $('<div><p class="slot">A</p><p class="slot">B</p></div>').appendTo("body");
const $new = $("<section>").text("New");
const $removed = $holder.find(".slot").first().replaceWith($new);
console.log(`removed=${$removed.get(0).tagName.toLowerCase()}; new=${$new.get(0).tagName.toLowerCase()}`);
const $inserted = $("<section>").text("Another").replaceAll($holder.find(".slot"));
console.log(`replaceAll inserted=${$inserted.get(0).tagName.toLowerCase()}; live sections=${$holder.children("section").length}`);
$holder.remove();removed=p; new=section
replaceAll inserted=section; live sections=2Ein vorhandener Dokumentknoten als Ersatz für ein einzelnes Ziel wird von seinem alten Ort verschoben. Er bleibt nicht als zusätzliche Kopie zurück. Der nächste Code vergleicht die Identität und zeigt, dass ein abgetrennter Knoten ohne Elternteil nicht ersetzt wird.
const $holder = $('<div><p class="slot">Placeholder</p><button type="button" class="source">Existing button</button></div>').appendTo("body");
const $source = $holder.find(".source");
const node = $source.get(0);
$holder.find(".slot").replaceWith($source);
console.log(`children=${$holder.children().length}; same node=${$holder.children().get(0) === node}`);
const $orphan = $("<p>Detached without parent</p>");
$orphan.replaceWith("<section>Replacement</section>");
console.log(`orphan tag=${$orphan.get(0).tagName.toLowerCase()}; connected=${$orphan.get(0).isConnected}`);
$holder.remove();children=1; same node=true
orphan tag=p; connected=falseDerselbe HTML-String mit derselben id für mehrere Ziele erzeugt doppelte IDs. Nutzen Sie Klassen für gemeinsame Gestaltung und eindeutige IDs bei Bedarf. Übertragen Sie die Verschiebung eines Einzelziels nicht pauschal auf alle Mehrziel-Kopierregeln. Braucht jedes Ziel einen neuen Knoten, erzeugen Sie ihn ausdrücklich je Funktionsaufruf.
Fehlende Handler und unsichtbare Änderungen
replaceWith bereinigt jQuery-Daten und Handler entfernter Knoten und ihrer Kinder. Bestehende .on()-Handler werden nicht auf neue Knoten kopiert. Verwenden Sie für wiederholt ersetzte Kinder delegierte .on()-Ereignisse auf einem erhaltenen Vorfahren oder initialisieren Sie neue Knoten. Diese Bereinigung garantiert nicht die Freigabe aller externen Zustände oder nativen addEventListener-Handler.
.css() oder .addClass() auf einer gespeicherten alten Auswahl kann Knoten außerhalb des Dokuments ändern. Verwenden Sie die neue Referenz oder eine neue eingegrenzte Auswahl. Prüfen Sie auch leere Auswahl und fehlende Eltern; die Rückgabe allein beweist keine Dokumentänderung.
Verketten Sie Benutzereingaben nicht direkt mit akzeptiertem HTML. Das Beispiel erstellt feste Tags und übergibt Namen mit .text(), Eingaben mit .val(), sodass <em> nicht als Tag interpretiert wird. Das gilt für diese Text- und Eingabewertkontexte, nicht als Bereinigung beliebigen HTML.
