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