CKTIS / JavaScript
Range: contentor comum, deslocamentos e estado colapsado
Lê os limites de um intervalo do DOM, encontra o nó comum mais próximo e verifica se ambos os limites indicam o mesmo ponto.
Versão: Current web platform; runtime support varies
Sintaxe
range.commonAncestorContainer
range.startOffset
range.endOffset
range.collapsedRange é uma interface do DOM, não faz parte do ECMAScript 2024. A disponibilidade destas propriedades depende da implementação do DOM no ambiente de execução, não da edição do ECMAScript. Não assumas que existem num ambiente sem DOM. Cada limite é um par formado por um nó e um deslocamento. Lê startOffset em conjunto com startContainer e endOffset em conjunto com endContainer.
Um deslocamento é uma posição contada a partir de zero, não o índice do último carácter incluído. Num nó CharacterData, como Text, conta as unidades de código UTF-16 antes do limite, não os caracteres percebidos pelo utilizador. Num contentor como Element, conta os nós filhos diretos antes do limite, incluindo texto e comentários, como em childNodes. 0 fica antes da primeira unidade ou do primeiro filho; o comprimento total fica depois do último.
commonAncestorContainer devolve o nó mais profundo que, para cada contentor de limite, é o próprio contentor ou um dos seus antepassados. Se os dois contentores forem o mesmo nó, devolve esse nó, mesmo que seja um Text. collapsed só é true quando ambos os limites têm o mesmo nó e o mesmo deslocamento. Deslocamentos iguais em nós diferentes não bastam.
As quatro propriedades de instância são só de leitura; startOffset, endOffset e collapsed são herdadas de AbstractRange. Usa setStart() e setEnd() para mover os limites. collapse(true) reduz o intervalo ao ponto inicial; collapse(false) ou collapse() reduz o intervalo ao ponto final. Um Range é dinâmico: as alterações ao DOM podem ajustar os seus limites.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>DOM Range boundary points</title>
<script>
{
const container = document.createElement('div');
const text = document.createTextNode('A😀B');
container.appendChild(text);
const range = document.createRange();
range.setStart(text, 3);
range.setEnd(container, 1);
const logRange = (expectedAncestor) => {
console.log(JSON.stringify([
range.commonAncestorContainer === expectedAncestor,
range.startOffset,
range.endOffset,
range.collapsed,
range.toString(),
]));
};
logRange(container);
range.collapse(true);
logRange(text);
}
</script>Resultado
[true,3,1,false,"B"] [true,3,3,true,""]
Guarda o exemplo como ficheiro HTML, abre-o num navegador e verifica o resultado na consola de desenvolvimento. O deslocamento `3` no nó de texto fica imediatamente a seguir ao emoji, que ocupa duas unidades de código UTF-16. O deslocamento `1` no elemento fica a seguir ao seu único filho. O intervalo contém, portanto, `B`. Depois de `collapse(true)`, os dois limites ficam no deslocamento `3` do nó de texto, que passa a ser o contentor comum.
Lições relacionadas
- JavaScript · Lição 33 · Intermédio · Versão: 3