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

CKTIS / JavaScript

Selection: contar intervalos com rangeCount e adicioná-los com addRange()

`rangeCount` indica quantos intervalos contém a seleção do documento e `addRange()` adiciona um intervalo do DOM. Para substituir a seleção por um só intervalo de forma compatível entre navegadores, limpe-a primeiro.

Versão: Current web platform; runtime support varies

Sintaxe

// Web platform: Selection API (not part of ECMAScript).
const selection = window.getSelection(); // Selection | null
if (selection !== null) {
  const count = selection.rangeCount;    // read-only number
  selection.addRange(range);            // takes a Range; returns undefined
}

Selection representa a seleção do documento ou a posição do cursor de texto. Obtenha o objeto com window.getSelection() e verifique se o resultado é null. Esta API pertence à plataforma Web, não ao ECMAScript 2024. Para o texto de um textarea ou de um tipo de input compatível, use antes o método setSelectionRange() do elemento.

rangeCount é uma propriedade numérica só de leitura. Conta objetos Range, não caracteres. 0 significa que não há nenhum intervalo. Pode ter rangeCount === 1 mesmo sem texto realçado: um intervalo reduzido a um único ponto também conta. Verifique se rangeCount > 0 antes de chamar getRangeAt(0), pois um índice fora dos limites lança uma exceção.

addRange(range) recebe um objeto Range e devolve undefined, pelo que o valor devolvido não indica se o intervalo foi adicionado. Crie um intervalo com document.createRange() e defina os seus limites, por exemplo com range.selectNodeContents(node) para um nó ligado ao mesmo documento. Um Range é dinâmico: alterações no DOM podem ajustar os seus limites.

A especificação permite, no máximo, um intervalo por seleção, mas o Firefox suporta vários. Um navegador limitado a um intervalo pode ignorar outra chamada a addRange() em vez de substituir o intervalo existente. Para definir um único intervalo novo de forma fiável, chame primeiro removeAllRanges(). Isto limpa a seleção anterior, não o conteúdo do documento.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Selection API example</title>
</head>
<body>
  <script>
    (() => {
      const selection = window.getSelection();
      if (selection === null) throw new Error("No document selection available");

      const paragraph = document.createElement("p");
      paragraph.textContent = "CKTIS";
      document.body.append(paragraph);

      try {
        const range = document.createRange();
        range.selectNodeContents(paragraph);

        selection.removeAllRanges();
        console.log(selection.rangeCount);
        selection.addRange(range);
        console.log(selection.rangeCount);
        console.log(selection.toString());
      } finally {
        selection.removeAllRanges();
        paragraph.remove();
      }
    })();
  </script>
</body>
</html>

Resultado

0
1
CKTIS

Guarde o exemplo como ficheiro `.html`, abra-o num separador à parte no navegador e consulte a consola de desenvolvimento. O código mostra `0` depois de limpar a seleção e, depois de adicionar o intervalo, mostra `1` e `CKTIS`. No fim, limpa a seleção e remove o parágrafo temporário, sem repor a seleção anterior.

Lições relacionadas

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

Fontes