Esta é uma tecnologia experimental
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.anchorNodeSomente leitura
Retorna o Node onde a seleção começou.
Selection.anchorOffsetSomente 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.focusNodeSomente leitura
Retorna o Node onde a seleção termina.
Selection.focusOffsetSomente 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.isCollapsedSomente 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.rangeCountSomente leitura
Retorna no número de intervalos da seleção.
Selection.typeSomente leitura
Retorna um DOMString descrevento o tipo da seleção atual.

Métodos

Selection.addRange()
Um objeto Range que será adicionado na seleção.
Selection.collapse()
Colapsa a seleção atual em um único ponto.
Selection.collapseToEnd()
Colapsa a seleção para o final do último intervalo na seleção.
Selection.collapseToStart()
Colapsa a seleção para o início do primeiro intervalo na seleção.
Selection.containsNode()
Indica se um certo nó é parte da seleção.
Selection.deleteFromDocument()
Apaga o conteúdo da seleção do documento.
Selection.empty()
Remove todos os intervalos da seleção. Este é um apelido para removeAllRanges() — Veja Selection.removeAllRanges() para mais detalhes.
Selection.extend()
Move o focus (final da seleção) para um ponto específico.
Selection.getRangeAt()
Retorna um objeto Range represetando um dos intervalos atualmente selecionados.
Selection.modify()
Altera a seleção atual.
Selection.removeRange()
Remove um intervalo da seleção.
Selection.removeAllRanges()
Remove todos os intervalos da seleção.
Selection.selectAllChildren()
Adiciona todos os filhos do nó especificado para a seleção.
Selection.setBaseAndExtent()
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()
Colapsa a seleção atual para um único ponto. Este é um apelido para collapse() — Veja Selection.collapse() para mais detalhes.
Selection.toString()
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() 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 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

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 14383WebKit 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. Um objeto de intervalo pode ser criado no DOM e programaticamente adicionada ou removida de uma seleção.

Especificações

Specification Status Comment
Selection API
The definition of 'Seleção' in that specification.
Rascunho atual A especificação da API de Seleção é baseada na especificação da API de edição HTML e focada na funcionalidade relacionada à seleção.
HTML Editing APIs
The definition of 'Seleção' in that specification.
Rascunho editorial Definição incial (antiga).

Compatibilidade de navegadores

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic support
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support Yes
Notes
Full support Yes
Notes
Notes The GlobalEventHandlers.onselectionchange and GlobalEventHandlers.onselectstart event handlers are supported as of Firefox 52.
IE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes The GlobalEventHandlers.onselectionchange and GlobalEventHandlers.onselectstart event handlers are supported as of Firefox 52.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
addRange
Experimental
Chrome Full support 1Edge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
anchorNode
Experimental
Chrome Full support 1Edge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
anchorOffset
Experimental
Chrome Full support 1Edge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
collapse
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
collapseToStart
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
collapseToEnd
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
containsNode
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support 4
Notes
Full support 4
Notes
Notes Before Firefox 35, the method didn't throw if node was null.
IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 4
Notes
Full support 4
Notes
Notes Before Firefox 35, the method didn't throw if node was null.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
deleteFromDocument
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support 55IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 55Opera Android Full support YesSafari iOS ? Samsung Internet Android ?
empty() as alias of removeAllRanges()
Experimental
Chrome Full support YesEdge ? Firefox Full support 55IE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support 55Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
extend
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
focusNode
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support 3.6IE Full support 10Opera Full support YesSafari Full support 5.1WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
focusOffset
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
getRangeAt
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
isCollapsed
Experimental
Chrome Full support 1Edge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
modify
ExperimentalNon-standard
Chrome Full support YesEdge ? Firefox Full support 4IE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
rangeCount
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
removeRange
Experimental
Chrome Full support 58Edge Full support YesFirefox Full support YesIE ? Opera Full support 45Safari No support NoWebView Android Full support 58Chrome Android Full support 58Edge Mobile Full support YesFirefox Android Full support YesOpera Android Full support 45Safari iOS No support NoSamsung Internet Android ?
removeAllRanges
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
selectAllChildren
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
setBaseAndExtent
Experimental
Chrome Full support YesEdge ? Firefox Full support 53IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support 53Opera Android Full support YesSafari iOS ? Samsung Internet Android ?
setPosition() as alias of collapse()
Experimental
Chrome Full support YesEdge ? Firefox Full support 55IE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support 55Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
toString
Experimental
Chrome Full support 1Edge Full support YesFirefox Full support YesIE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS ? Samsung Internet Android ?
type
Experimental
Chrome Full support YesEdge Full support YesFirefox Full support 57IE Full support YesOpera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 57Opera Android Full support YesSafari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
See implementation notes.
See implementation notes.

Veja também

Notas da Gecko

Etiquetas do documento e colaboradores

Colaboradores desta página: mdnwebdocs-bot, adrianowead
Última atualização por: mdnwebdocs-bot,