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

CKTIS / JavaScript

Selection — seleção do documento

Selection representa a seleção do documento. Aprende sobre rangeCount e como adicionar um intervalo com addRange.

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

const selection = window.getSelection();
selection.rangeCount;
selection.removeAllRanges();
selection.addRange(range);

Selection representa a seleção do documento; Range define os respetivos limites. Obtém-na através de window.getSelection() e verifica se o resultado é null. É uma API Web, não uma funcionalidade ECMAScript; o Node 24 não comprova o suporte nos navegadores.

Selection.rangeCount é apenas de leitura: a especificação determina o valor 0 se a seleção estiver vazia ou os seus limites estiverem fora da árvore do documento, e 1 nos restantes casos. Um intervalo colapsado também pode resultar num valor de 1 — isso não significa que exista texto selecionado.

Quando Selection.addRange(range) adiciona um intervalo, mantém uma referência, não uma cópia. Segundo a especificação, o método não faz nada se o intervalo estiver fora da árvore do documento ou se Selection.rangeCount for diferente de 0. No entanto, o Firefox permite adicionar vários intervalos, pelo que Selection.rangeCount pode ser superior a 1 nesse navegador. Não partas do princípio de que todos os navegadores suportam vários intervalos. Para substituir a seleção, chama removeAllRanges() antes de adicionar o novo intervalo.

Exemplos

(() => {
  const selection = window.getSelection();
  if (!selection || !document.body) {
    throw new Error('An active browser document with a body is required.');
  }

  const paragraph = document.createElement('p');
  paragraph.textContent = 'Hello Selection';
  document.body.append(paragraph);

  const range = document.createRange();
  range.setStart(paragraph.firstChild, 6);
  range.setEnd(paragraph.firstChild, 15);

  try {
    selection.removeAllRanges();
    selection.addRange(range);
    console.log(selection.rangeCount + ': ' + selection.toString());

    range.collapse(true);
    console.log(selection.rangeCount + ': ' + selection.isCollapsed);
  } finally {
    selection.removeAllRanges();
    paragraph.remove();
  }
})();

Resultado

1: Selection
1: true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes