Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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() → Range

Range 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