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

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.collapsed

Range é 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

Fontes