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.:


```js
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:


```js
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:

* `Selection.collapse()` (en-US)
* `Selection.collapseToStart()` (en-US)
* `Selection.collapseToEnd()` (en-US)
* `Selection.extend()` (en-US)
* `Selection.selectAllChildren()` (en-US)
* `Selection.addRange()` (en-US)
* `Selection.setBaseAndExtent()` (en-US)

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

* `Range.setStart()` (en-US)
* `Range.setEnd()` (en-US)
* `Range.setStartBefore()` (en-US)
* `Range.setStartAfter()` (en-US)
* `Range.setEndBefore()` (en-US)
* `Range.setEndAfter()` (en-US)
* `Range.collapse()` (en-US)
* `Range.selectNode()` (en-US)
* `Range.selectNodeContents()` (en-US)
### 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 with JavaScript enabled. Enable JavaScript to view data.

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)