Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Range — um intervalo vivo na árvore DOM

Range descreve um fragmento do DOM entre dois limites. Permite extrair, eliminar e inserir conteúdo, enquanto os seus limites reagem automaticamente às alterações da árvore.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const range = document.createRange();
range.setStart(node, startOffset);
range.setEnd(node, endOffset);
range.extractContents();
range.insertNode(node);

Range é um intervalo vivo definido por dois pares de nó e deslocamento. Cria-se com document.createRange() ou new Range(). É uma API Web do padrão DOM, não uma funcionalidade de uma edição específica do ECMAScript; a presença do Node 24 num repositório não comprova a sua disponibilidade. O exemplo requer um DOM de navegador.

Range.startOffset e Range.endOffset contam unidades de código UTF-16 em CharacterData, mas, nos elementos, contam nós filhos e não caracteres. Range.commonAncestorContainer devolve o nó comum mais profundo que contém ambos os limites; pode ser o próprio nó de texto. Range.collapsed significa que os limites são idênticos, não apenas que o texto está vazio.

Range.extractContents() remove conteúdo e devolve um DocumentFragment: os nós totalmente contidos são movidos, enquanto as estruturas parcialmente contidas são copiadas conforme necessário. Range.deleteContents() remove conteúdo sem devolver um fragmento. Ambas as operações colapsam o intervalo. Range.insertNode(node) insere no início em vez de substituir o conteúdo; pode dividir um nó de texto e expandir um intervalo colapsado.

Range.setStartAfter(node) coloca o início depois do nó no respetivo pai; o nó tem de ter um pai. Range.collapse(true) colapsa o intervalo para o início, enquanto Range.collapse(false) ou Range.collapse() o colapsa para o fim. Range.cloneRange() cria um intervalo vivo separado com os mesmos limites, não uma cópia do DOM nem uma captura imutável: alterações posteriores podem afetar ambos os intervalos.

Exemplos

(() => {
  const host = document.createElement('div');
  host.textContent = 'ABCDE';
  const range = document.createRange();
  range.setStart(host.firstChild, 1);
  range.setEnd(host.firstChild, 4);
  console.log(range.commonAncestorContainer === host.firstChild);
  console.log(range.startOffset, range.endOffset, range.collapsed);

  const copy = range.cloneRange();
  copy.collapse(true);
  console.log(copy.collapsed, range.collapsed);

  const fragment = range.extractContents();
  console.log(fragment.textContent, host.textContent, range.collapsed);
  const mark = document.createElement('mark');
  mark.appendChild(fragment);
  range.insertNode(mark);
  range.setStartAfter(mark);
  range.collapse(true);
  console.log(host.textContent, range.startOffset, range.endOffset);

  range.selectNode(mark);
  range.deleteContents();
  console.log(host.textContent, range.collapsed);
})();

Resultado

true
1 4 false
true false
BCD AE true
ABCDE 2 2
AE true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes