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