CKTIS / JavaScript
Selection.getRangeAt — obter um intervalo de seleção
Selection.getRangeAt(0) devolve o objeto Range associado à seleção do documento, não uma cópia.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
selection.getRangeAt(index)selection.getRangeAt(index) disponibiliza o intervalo da seleção. É uma API Web do navegador, não uma funcionalidade ECMAScript; o Node 24 não comprova o seu suporte.
Antes de chamar o método com o índice 0, verifica se selection !== null e selection.rangeCount > 0. A especificação exige que seja lançada a exceção IndexSizeError se o índice for diferente de 0, se a seleção estiver vazia ou se uma das suas extremidades estiver fora da árvore do documento. Os navegadores nem sempre seguem esta regra: o Firefox pode disponibilizar vários intervalos de seleção, pelo que um índice diferente de 0 pode funcionar. Se uma extremidade estiver numa árvore do Shadow DOM, não partas do princípio de que o navegador lança esta exceção. Uma seleção reduzida à posição do cursor pode continuar a ter um intervalo.
O resultado é uma referência: modificar o intervalo afeta a seleção enquanto ambos permanecerem associados. Chamadas repetidas com o mesmo índice devolvem o mesmo objeto, a menos que o intervalo seja substituído ou removido. A especificação é um Working Draft, não uma tabela de compatibilidade dos navegadores.
Exemplos
(() => {
const selection = window.getSelection();
if (!selection || !document.body) {
throw new Error("An active browser document is required.");
}
const element = document.createElement("p");
element.textContent = "Hello world";
document.body.append(element);
try {
selection.removeAllRanges();
const range = document.createRange();
range.setStart(element.firstChild, 0);
range.setEnd(element.firstChild, 5);
selection.addRange(range);
if (selection.rangeCount === 0) {
throw new Error("No selection range is available.");
}
const selectedRange = selection.getRangeAt(0);
console.log(selectedRange.toString());
console.log(selectedRange === selection.getRangeAt(0));
} finally {
selection.removeAllRanges();
element.remove();
}
})();Resultado
Hello true
O código e o resultado foram verificados num ambiente Chromium isolado. O exemplo obtém o único intervalo com o índice `0` e verifica se uma segunda chamada devolve o mesmo objeto. Não testa índices diferentes de `0` nem extremidades numa árvore do Shadow DOM.