CKTIS / JavaScript
Edycja DOM za pomocą Range
Wycinaj, wstawiaj i usuwaj zawartość DOM. Dowiedz się, jak ustawiać granice zakresu, jak sprowadzać go do jednego punktu i co faktycznie kopiuje `cloneRange()`.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
range.extractContents() → DocumentFragment
range.insertNode(newNode) → undefined
range.deleteContents() → undefined
range.setStartAfter(referenceNode) → undefined
range.collapse() → undefined
range.collapse(toStart) → undefined
range.cloneRange() → RangeRange to żywy zakres DOM opisany dwiema granicami. Każda granica to para: węzeł kontenera i przesunięcie. W węźle tekstowym przesunięcie liczy jednostki kodowe UTF-16, a w elemencie — węzły potomne przed granicą, nie tylko elementy potomne. Range należy do interfejsu DOM, nie do ECMAScript 2024; środowisko musi udostępniać DOM.
extractContents() usuwa zawartość zakresu i zwraca DocumentFragment: przenosi węzły całkowicie objęte zakresem, kopiuje wybrane części tekstu i w razie potrzeby odtwarza ich strukturę w częściowo objętych elementach, klonując te elementy. deleteContents() usuwa zawartość bez zwracania fragmentu (undefined). Obie metody sprowadzają zakres do jednego punktu; jeśli zakres już był sprowadzony do punktu, wycięcie zwraca pusty fragment, a usunięcie nic nie robi.
insertNode(newNode) wstawia węzeł na początku zakresu, nie zastępując jego zawartości. Jeśli granica wypada w węźle tekstowym, metoda dzieli go w tym miejscu. Jeśli argumentem jest DocumentFragment, przenosi jego dzieci i pozostawia pusty fragment. Wstawienie może rozciągnąć zakres sprowadzony do punktu. Niedozwolona hierarchia węzłów może spowodować HierarchyRequestError. Metoda nie oczyszcza zawartości; niezaufany zwykły tekst umieszczaj w węźle tekstowym, zamiast interpretować go jako HTML.
setStartAfter(referenceNode) ustawia początek tuż za węzłem, w jego rodzicu. Brak rodzica powoduje InvalidNodeTypeError. Jeśli nowy początek wypada za końcem lub w innym drzewie, koniec również trafia w ten punkt. collapse(true) sprowadza zakres do początku, a collapse(false) i collapse() — do końca. Te dwie metody i insertNode() zwracają undefined.
cloneRange() zwraca odrębny Range z tymi samymi początkowymi granicami, bez kopiowania węzłów. Zmiana granicy jednego zakresu nie przestawia bezpośrednio drugiego, ale oba pozostają żywe: mutacje DOM mogą zmienić granice obu. Klon nie jest migawką zawartości.
Przykłady
<!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>Wynik
before: B / true moved: AC / XBY / 0 final: XB / true
Zapisz przykład jako plik HTML, otwórz go w przeglądarce i sprawdź wynik w konsoli. Sprowadzenie kopii do punktu pozostawia `B` w pierwotnym zakresie. Wycięty węzeł trafia między `X` i `Y`, fragment zostaje opróżniony, a na końcu usuwane jest `Y`.
Powiązane lekcje
- JavaScript · Lekcja 33 · Średniozaawansowany · Wersja: 3
Źródła
- 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