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

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.

Fontes