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

CKTIS / JavaScript

Editar o DOM com Range

Recorta, insere e elimina conteúdo do DOM. Aprende a posicionar os limites de um intervalo, a reduzi-lo a um ponto e a perceber o que `cloneRange()` copia.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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

Um Range é um intervalo dinâmico do DOM, com um limite inicial e um limite final. Cada limite é definido por um nó contentor e um deslocamento. Num nó de texto, o deslocamento conta unidades de código UTF-16; num elemento, conta os nós filhos anteriores ao limite, não apenas os elementos filhos. Range pertence ao DOM, não ao ECMAScript 2024; o ambiente de execução tem de disponibilizar um DOM.

extractContents() retira o conteúdo do intervalo e devolve um DocumentFragment. Move os nós totalmente contidos, copia as partes de texto selecionadas e clona, se necessário, os elementos parcialmente contidos para conservar a estrutura. deleteContents() retira o conteúdo sem devolver um fragmento (undefined). Ambos os métodos reduzem o intervalo a um ponto. Se já estiver reduzido, a extração devolve um fragmento vazio e a eliminação não faz nada.

insertNode(newNode) insere no limite inicial sem substituir o conteúdo do intervalo. Se o limite estiver num nó de texto, divide-o nesse ponto. Se receber um DocumentFragment, move os seus filhos e deixa o fragmento vazio. A inserção pode alargar um intervalo reduzido a um ponto. Uma hierarquia inválida pode causar HierarchyRequestError. A inserção não higieniza o conteúdo: põe texto simples não fiável num nó de texto, em vez de o interpretar como HTML.

setStartAfter(referenceNode) coloca o início imediatamente a seguir ao nó de referência, dentro do seu nó pai. Se não houver nó pai, ocorre InvalidNodeTypeError. Se o novo início ficar depois do fim ou noutra árvore, o fim também passa para esse ponto. collapse(true) reduz o intervalo ao início; collapse(false) e collapse() reduzem-no ao fim. Estes dois métodos e insertNode() devolvem undefined.

cloneRange() devolve um Range distinto com limites inicialmente iguais, sem copiar nós. Alterar um limite de um intervalo não reposiciona diretamente o outro, mas ambos continuam dinâmicos: as mutações do DOM podem ajustar os limites dos dois. O clone não é uma cópia instantânea do conteúdo.

Exemplos

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

Resultado

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

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta a consola de programador. Reduzir a cópia a um ponto mantém `B` no intervalo original. O nó extraído é inserido entre `X` e `Y`, o fragmento fica vazio e, por fim, `Y` é eliminado.

Lições relacionadas

  • JavaScript · Lição 33 · Intermédio · Versão: 3

Fontes