Seleção

Experimental: Esta é uma tecnologia experimental (en-US)
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.

Um objeto Selection representa um intervalo do texto selecionado pelo usuário ou a posição atual do cursor. Para obter o objeto Selection para inspecionar ou modificar, use Window.getSelection().

O usuário pode fazer a seleção da esquerda para a direita (na orientação do documento) ou da direita para a esquerta (orientação inversa do documento). O atributo anchor (âncora) é onde o usuário iniciou a seleção e o atributo focus (foco) é onde o usuário terminou a seleção. Se você fizer a seleção utilizando um mouse no desktop, o anchor é definido onde você pressionou o botão do mouse e o focus é definido onde você soltou o botão do mouse. Anchor e focus não devem ser confundidos com a posição inicial e final da seleção, pois o anchor pode ser definido antes do focus ou vice versa, dependendo da direção em que você fez sua seleção.

Propriedades

Selection.anchorNode (en-US)Somente leitura: Retorna o Node onde a seleção começou.
Selection.anchorOffset (en-US)Somente leitura: Retorna um número representando o deslocamento do anchor dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o anchor (clique inicial da seleção). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o anchor.
Selection.focusNode (en-US)Somente leitura: Retorna o Node onde a seleção termina.
Selection.focusOffset (en-US)Somente leitura: Retorna um número representando o deslocamento do focus dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o focus (posição onde o mouse foi solto). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o focus.
Selection.isCollapsed (en-US)Somente leitura: Retorna um valor booleano indicando se o início e o final da seleção são a mesma posição, ou seja, começou e terminou no mesmo lugar.
Selection.rangeCount (en-US)Somente leitura: Retorna no número de intervalos da seleção.
Selection.type (en-US)Somente leitura: Retorna um DOMString descrevento o tipo da seleção atual.

Métodos

Selection.addRange() (en-US): Um objeto Range (en-US) que será adicionado na seleção.
Selection.collapse() (en-US): Colapsa a seleção atual em um único ponto.
Selection.collapseToEnd() (en-US): Colapsa a seleção para o final do último intervalo na seleção.
Selection.collapseToStart() (en-US): Colapsa a seleção para o início do primeiro intervalo na seleção.
Selection.containsNode() (en-US): Indica se um certo nó é parte da seleção.
Selection.deleteFromDocument() (en-US): Apaga o conteúdo da seleção do documento.
Selection.empty() (en-US): Remove todos os intervalos da seleção. Este é um apelido para removeAllRanges() — Veja Selection.removeAllRanges() (en-US) para mais detalhes.
Selection.extend() (en-US): Move o focus (final da seleção) para um ponto específico.
Selection.getRangeAt() (en-US): Retorna um objeto Range (en-US) represetando um dos intervalos atualmente selecionados.
Selection.modify() (en-US) Non-standard: Altera a seleção atual.
Selection.removeRange() (en-US): Remove um intervalo da seleção.
Selection.removeAllRanges() (en-US): Remove todos os intervalos da seleção.
Selection.selectAllChildren() (en-US): Adiciona todos os filhos do nó especificado para a seleção.
Selection.setBaseAndExtent() (en-US): Define que a seleção será um intervalo incluindo todos ou partes dos dois nós DOM especificados, e qualquer conteúdo entre esses nós.
Selection.setPosition() (en-US): Colapsa a seleção atual para um único ponto. Este é um apelido para collapse() — Veja Selection.collapse() (en-US) para mais detalhes.
Selection.toString() (en-US): Retorna uma string atualmente representada pelo objeto selection, i.e. o texto atualmente selecionado.

Notas

Representação da seleção em formato de String

Chamando a função Selection.toString() (en-US) retorna o texto selecionado, e.g.:

var selObj = window.getSelection();
window.alert(selObj);

Perceba que usando um objeto selection como argumento de window.alert executará o metodo toString automaticamente.

Multiplos intervalos em uma seleção

Um objeto selection representa os intervalos (en-US) que o usuário selecionou. Normalmente é apenas um intervalo, acessado da seguinte forma:

var selObj = window.getSelection();
var range = selObj.getRangeAt(0);

selObj é um objeto selection
range é um objeto Range (en-US)

Como consta nas Especificações da API de seleção, a API foi inicialmente criada pela Netscape e usados multiplos intervalos, por instância, para permitir ao usuário selecionar uma coluna de uma <table>. Outros navegadores como Gecko não implementaram multiplos intervalos, e a especificação exige que a seleção sempre tenha um único intervalo.

Seleção e foco de input

Seleção e foco de input (indicado por Document.activeElement) tem uma relação complexa, que depende do navegador. Para um código compatível com vários navegadores, o melhor é manter os códigos separados.

O Safari e o Chrome (ao contrário do Firefox) historicamente foca no elemento contendo a seleção quando a seleção é modificada programaticamente, mas isto pode mudar no futuro (veja W3C bug 14383 e WebKit bug 38696).

Comportamento da API de Seleção em termos de edição e alterações de foco do host

A API de Seleção tem um comportamento comum (i.e. compartilhado entre navegadores) que define como o comportamento do foco muda para elemento editável, após alguns desses métodos serem executados.

Os comportamentos são que um elemento editado recebe o foco se anteriormente a seleção estiver fora dele, então um método da API de seleção é executado e causa uma nova seleção que será feita em um único intervalo dentro do elemento sendo editado. O foco então é movido para o final do elemento.

Nota: Os métodos da API de seleção, move o foco apenas para o elemento sendo editado, não para outro elemento que pode receber o foco (e.g. <a>).

O comportamento acima é aplicado para as seleções feitas usando os seguintes métodos:

e quando o intervalo é modificado usando os seguintes métodos:

Glossário

Outras palavras chaves usadas nesta seção.

anchor: O anchor de uma seleção é o ponto inicial da seleção. Quando a seleção é feita com um mouse, é onde o botão do mouse é inicialmente pressionado. Quando o usuário altera a seleção usando o mouse ou teclado, o anchor não move.
Elemento editável: Um elemento editável — i.e. um elemento HTML com o atributo contenteditable definido, ou o HTML filho de um documento estiver com o designMode habilitado.
foco de uma seleção: O foco da seleção é o ponto final da seleção. Quando feita a seleção com um mouse, o focus é onde o botão do mouse foi solto. Quando o usuário muda a seleção usando o mouse ou teclado, o focus é o final da seleção que move. Nota: Não é o mesmo que o elemento selecionado do documento, como retornado em document.activeElement.
intervalo: Um intervalo é uma parte contínua do documento. Um intervalo pode conter nós inteiros ou partes de nós, como uma parte de um text node. Um usuário normalmente irá selecionar um único intervalo por vez, mas é possível que o usuário selecione multiplos intervalos (e.g. usando a tecla Control). Um intervalo pode ser obtido de uma seleção como um objeto range (en-US). Um objeto de intervalo pode ser criado no DOM e programaticamente adicionada ou removida de uma seleção.

Especificações

Specification
Selection API # selection-interface

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também

Window.getSelection, Document.getSelection, Range (en-US)
Selection-related events: selectionchange and selectstart
HTML inputs provide simpler helper APIs for working with selection (see HTMLInputElement.setSelectionRange())
Document.activeElement, HTMLElement.focus() (en-US), and HTMLElement.blur() (en-US)