CKTIS / JavaScript
Den DOM mit Range bearbeiten
DOM-Inhalte ausschneiden, einfügen und löschen: So setzt du die Grenzen eines Bereichs, reduzierst ihn auf einen Punkt und erkennst, was `cloneRange()` kopiert.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
range.extractContents() → DocumentFragment
range.insertNode(newNode) → undefined
range.deleteContents() → undefined
range.setStartAfter(referenceNode) → undefined
range.collapse() → undefined
range.collapse(toStart) → undefined
range.cloneRange() → RangeEin Range ist ein lebender DOM-Bereich mit einer Start- und einer Endgrenze. Jede Grenze besteht aus einem Containerknoten und einem Offset. In einem Textknoten zählt der Offset UTF-16-Codeeinheiten, in einem Element die vorhergehenden Kindknoten, nicht nur Kindelemente. Range gehört zum DOM, nicht zu ECMAScript 2024; die Laufzeitumgebung muss ein DOM bereitstellen.
extractContents() entfernt den Inhalt des Bereichs und gibt ein DocumentFragment zurück. Vollständig enthaltene Knoten werden verschoben, ausgewählte Textabschnitte kopiert und teilweise enthaltene Elemente bei Bedarf geklont, damit ihre Struktur erhalten bleibt. deleteContents() entfernt den Inhalt, gibt aber kein Fragment zurück (undefined). Beide Methoden reduzieren den Bereich auf einen Punkt. Ist er bereits auf einen Punkt reduziert, liefert das Ausschneiden ein leeres Fragment und das Löschen ändert nichts.
insertNode(newNode) fügt an der Startgrenze ein, ohne den Inhalt des Bereichs zu ersetzen. Liegt die Grenze in einem Textknoten, wird dieser dort geteilt. Bei einem DocumentFragment werden seine Kinder verschoben und das Fragment bleibt leer. Die Einfügung kann einen auf einen Punkt reduzierten Bereich erweitern. Eine unzulässige Baumstruktur kann HierarchyRequestError auslösen. Die Methode bereinigt keine Inhalte; nicht vertrauenswürdigen Klartext solltest du in einen Textknoten schreiben, statt ihn als HTML zu parsen.
setStartAfter(referenceNode) setzt den Anfang im Elternknoten direkt hinter den Referenzknoten. Hat dieser keinen Elternknoten, tritt InvalidNodeTypeError auf. Liegt der neue Anfang hinter dem Ende oder in einem anderen Baum, wird auch das Ende dorthin gesetzt. collapse(true) reduziert den Bereich auf seinen Anfang, collapse(false) und collapse() auf sein Ende. Diese beiden Methoden und insertNode() geben undefined zurück.
cloneRange() gibt einen separaten Range mit anfangs gleichen Grenzen zurück, ohne Knoten zu kopieren. Das Setzen einer Grenze verschiebt die des anderen Bereichs nicht direkt. Beide Bereiche bleiben jedoch lebend: DOM-Änderungen können ihre Grenzen anpassen. Der Klon ist keine Momentaufnahme des Inhalts.
Beispiele
<!doctype html>
<meta charset="utf-8">
<title>Editing the DOM with Range</title>
<script>
(() => {
const source = document.createElement('p');
const target = document.createElement('p');
const item = document.createElement('em');
item.textContent = 'B';
source.append('A', item, 'C');
target.textContent = 'XY';
const cut = document.createRange();
cut.selectNode(item);
const copy = cut.cloneRange();
copy.collapse(true);
console.log(`before: ${cut.toString()} / ${copy.collapsed}`);
const fragment = cut.extractContents();
const edit = document.createRange();
edit.setStart(target.firstChild, 1);
edit.collapse(true);
edit.insertNode(fragment);
console.log(`moved: ${source.textContent} / ${target.textContent} / ${fragment.childNodes.length}`);
edit.setStartAfter(item);
edit.collapse(true);
edit.setEnd(target, target.childNodes.length);
edit.deleteContents();
console.log(`final: ${target.textContent} / ${edit.collapsed}`);
})();
</script>Ergebnis
before: B / true moved: AC / XBY / 0 final: XB / true
Speichere das Beispiel als HTML-Datei, öffne sie im Browser und prüfe die Ausgabe in der Entwicklerkonsole. Das Reduzieren der Kopie lässt `B` im ursprünglichen Bereich. Der ausgeschnittene Knoten kommt zwischen `X` und `Y`, das Fragment wird leer und anschließend wird `Y` gelöscht.
Zugehörige Lektionen
- JavaScript · Lektion 33 · Mittlere Stufe · Version: 3
Quellen
- Range - Web APIs | MDN
- Range: extractContents() method - Web APIs | MDN
- Range: insertNode() method - Web APIs | MDN
- Range: deleteContents() method - Web APIs | MDN
- Range: setStartAfter() method - Web APIs | MDN
- Range: collapse() method - Web APIs | MDN
- Range: cloneRange() method - Web APIs | MDN
- Range: setStart() method - Web APIs | MDN
- StaticRange - Web APIs | MDN
- DOMException - Web APIs | MDN
- Element: innerHTML property - Web APIs | MDN