Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Modificare il DOM con Range

Taglia, inserisci ed elimina contenuti del DOM. Impara a impostare gli estremi di un intervallo, a ridurlo a un punto e a capire che cosa copia `cloneRange()`.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

range.extractContents() → DocumentFragment
range.insertNode(newNode) → undefined
range.deleteContents() → undefined
range.setStartAfter(referenceNode) → undefined
range.collapse() → undefined
range.collapse(toStart) → undefined
range.cloneRange() → Range

Un Range è un intervallo dinamico del DOM con un estremo iniziale e uno finale. Ogni estremo è una coppia formata da un nodo contenitore e un offset. In un nodo di testo l’offset conta le unità di codice UTF-16; in un elemento conta i nodi figli che precedono l’estremo, non solo gli elementi figli. Range fa parte del DOM, non di ECMAScript 2024: l’ambiente di esecuzione deve fornire un DOM.

extractContents() rimuove il contenuto dell’intervallo e restituisce un DocumentFragment. Sposta i nodi interamente compresi, copia le porzioni di testo selezionate e, quando serve, clona gli elementi compresi solo in parte per conservarne la struttura. deleteContents() rimuove il contenuto senza restituire un frammento (undefined). Entrambi i metodi riducono l’intervallo a un punto. Se è già ridotto, l’estrazione restituisce un frammento vuoto e l’eliminazione non fa nulla.

insertNode(newNode) inserisce all’estremo iniziale senza sostituire il contenuto dell’intervallo. Se l’estremo è in un nodo di testo, lo divide in quel punto. Se riceve un DocumentFragment, ne sposta i figli e lo lascia vuoto. L’inserimento può estendere un intervallo ridotto a un punto. Una gerarchia non valida può causare HierarchyRequestError. L’inserimento non sanifica il contenuto: inserisci il testo semplice non attendibile in un nodo di testo, senza interpretarlo come HTML.

setStartAfter(referenceNode) posiziona l’inizio subito dopo il nodo di riferimento, nel suo genitore. Se il nodo non ha un genitore, si verifica InvalidNodeTypeError. Se il nuovo inizio segue la fine o si trova in un altro albero, anche la fine viene spostata in quel punto. collapse(true) riduce l’intervallo all’inizio; collapse(false) e collapse() lo riducono alla fine. Questi due metodi e insertNode() restituiscono undefined.

cloneRange() restituisce un Range separato con estremi inizialmente identici, senza copiare nodi. Impostare un estremo di un intervallo non riposiziona direttamente l’altro intervallo, ma entrambi restano dinamici: le mutazioni del DOM possono modificarne gli estremi. Il clone non è un’istantanea del contenuto.

Esempi

<!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>

Risultato

before: B / true
moved: AC / XBY / 0
final: XB / true

Salva l’esempio come file HTML, aprilo in un browser e controlla l’output nella console di sviluppo. Ridurre la copia a un punto lascia `B` nell’intervallo originale. Il nodo estratto viene inserito tra `X` e `Y`, il frammento si svuota e infine `Y` viene eliminata.

Lezioni correlate

  • JavaScript · Lezione 33 · Intermedio · Versione: 3

Fonti