1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
---
title: Seleção
slug: Web/API/Seleção
tags:
- API
- Experimental
- Interface
- Referencia
- Seleção
translation_of: Web/API/Selection
---
<div>{{ ApiRef("DOM") }}{{SeeCompatTable}}</div>
<p>Um objeto <code><strong>Selection</strong></code> 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 {{DOMxRef("Window.getSelection()")}}.</p>
<p>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 <strong>anchor (âncora)</strong> é onde o usuário iniciou a seleção e o atributo <strong>focus (foco)</strong> é onde o usuário terminou a seleção. Se você fizer a seleção utilizando um mouse no desktop, o <em>anchor</em> é definido onde você pressionou o botão do mouse e o <em>focus</em> é definido onde você soltou o botão do mouse. <em>Anchor</em> e <em>focus</em> não devem ser confundidos com a posição inicial e final da seleção, pois o <em>anchor</em> pode ser definido antes do <em>focus</em> ou vice versa, dependendo da direção em que você fez sua seleção.</p>
<h2 id="Properties" name="Properties">Propriedades</h2>
<dl>
<dt>{{DOMxRef("Selection.anchorNode")}}{{ReadOnlyInline}}</dt>
<dd>Retorna o {{DOMxRef("Node")}} onde a seleção começou.</dd>
<dt>{{DOMxRef("Selection.anchorOffset")}}{{ReadOnlyInline}}</dt>
<dd>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.</dd>
<dt>{{DOMxRef("Selection.focusNode")}}{{ReadOnlyInline}}</dt>
<dd>Retorna o {{DOMxRef("Node")}} onde a seleção termina.</dd>
<dt>{{DOMxRef("Selection.focusOffset")}}{{ReadOnlyInline}}</dt>
<dd>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.</dd>
<dt>{{DOMxRef("Selection.isCollapsed")}}{{ReadOnlyInline}}</dt>
<dd>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.</dd>
<dt>{{DOMxRef("Selection.rangeCount")}}{{ReadOnlyInline}}</dt>
<dd>Retorna no número de intervalos da seleção.</dd>
<dt>{{DOMxRef("Selection.type")}}{{ReadOnlyInline}}</dt>
<dd>Retorna um {{DOMxRef("DOMString")}} descrevento o tipo da seleção atual.</dd>
</dl>
<h2 id="Methods" name="Methods">Métodos</h2>
<dl>
<dt>{{DOMxRef("Selection.addRange()")}}</dt>
<dd>Um objeto {{DOMxRef("Range")}} que será adicionado na seleção.</dd>
<dt>{{DOMxRef("Selection.collapse()")}}</dt>
<dd>Colapsa a seleção atual em um único ponto.</dd>
<dt>{{DOMxRef("Selection.collapseToEnd()")}}</dt>
<dd>Colapsa a seleção para o final do último intervalo na seleção.</dd>
<dt>{{DOMxRef("Selection.collapseToStart()")}}</dt>
<dd>Colapsa a seleção para o início do primeiro intervalo na seleção.</dd>
<dt>{{DOMxRef("Selection.containsNode()")}}</dt>
<dd>Indica se um certo nó é parte da seleção.</dd>
<dt>{{DOMxRef("Selection.deleteFromDocument()")}}</dt>
<dd>Apaga o conteúdo da seleção do documento.</dd>
<dt>{{DOMxRef("Selection.empty()")}}</dt>
<dd>Remove todos os intervalos da seleção. Este é um apelido para <code>removeAllRanges()</code> — Veja {{DOMxRef("Selection.removeAllRanges()")}} para mais detalhes.</dd>
<dt>{{DOMxRef("Selection.extend()")}}</dt>
<dd>Move o focus (final da seleção) para um ponto específico.</dd>
<dt>{{DOMxRef("Selection.getRangeAt()")}}</dt>
<dd>Retorna um objeto {{DOMxRef("Range")}} represetando um dos intervalos atualmente selecionados.</dd>
<dt>{{DOMxRef("Selection.modify()")}}{{Non-standard_Inline}}</dt>
<dd>Altera a seleção atual.</dd>
<dt>{{DOMxRef("Selection.removeRange()")}}</dt>
<dd>Remove um intervalo da seleção.</dd>
<dt>{{DOMxRef("Selection.removeAllRanges()")}}</dt>
<dd>Remove todos os intervalos da seleção.</dd>
<dt>{{DOMxRef("Selection.selectAllChildren()")}}</dt>
<dd>Adiciona todos os filhos do nó especificado para a seleção.</dd>
<dt>{{DOMxRef("Selection.setBaseAndExtent()")}}</dt>
<dd>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.</dd>
<dt>{{DOMxRef("Selection.setPosition()")}}</dt>
<dd>Colapsa a seleção atual para um único ponto. Este é um apelido para <code>collapse()</code> — Veja {{DOMxRef("Selection.collapse()")}} para mais detalhes.</dd>
<dt>{{DOMxRef("Selection.toString()")}}</dt>
<dd>Retorna uma string atualmente representada pelo objeto selection, i.e. o texto atualmente selecionado.</dd>
</dl>
<h2 id="Notas">Notas</h2>
<h3 id="Representação_da_seleção_em_formato_de_String">Representação da seleção em formato de String</h3>
<p>Chamando a função {{DOMxRef("Selection.toString()")}} retorna o texto selecionado, e.g.:</p>
<pre class="brush: js">var selObj = window.getSelection();
window.alert(selObj);
</pre>
<p>Perceba que usando um objeto selection como argumento de <code>window.alert</code> executará o metodo <code>toString</code> automaticamente.</p>
<h3 id="Multiplos_intervalos_em_uma_seleção">Multiplos intervalos em uma seleção</h3>
<p>Um objeto selection representa os {{DOMxRef("range","intervalos")}} que o usuário selecionou.<br>
Normalmente é apenas um intervalo, acessado da seguinte forma:</p>
<div style="overflow: hidden;">
<pre class="brush:js">var selObj = window.getSelection();
var range = selObj.getRangeAt(0);</pre>
</div>
<ul>
<li><code>selObj</code> é um objeto selection</li>
<li><code>range</code> é um objeto {{DOMxRef("Range")}}</li>
</ul>
<p>Como consta nas <a href="http://www.w3.org/TR/selection-api/#h_note_15">Especificações da API de seleção</a>, a API foi inicialmente criada pela Netscape e usados multiplos intervalos, por instância, para permitir ao usuário selecionar uma coluna de uma {{HTMLElement("table")}}. Outros navegadores como Gecko não implementaram multiplos intervalos, e a especificação exige que a seleção sempre tenha um único intervalo.</p>
<h3 id="Seleção_e_foco_de_input">Seleção e foco de input</h3>
<p>Seleção e foco de input (indicado por {{DOMxRef("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.</p>
<p>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 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14383">W3C bug 14383</a> e {{WebKitBug("38696")}}).</p>
<h3 id="Comportamento_da_API_de_Seleção_em_termos_de_edição_e_alterações_de_foco_do_host">Comportamento da API de Seleção em termos de edição e alterações de foco do host</h3>
<p>A API de Seleção tem um comportamento comum (i.e. compartilhado entre navegadores) que define como o comportamento do foco muda para <strong>elemento editável</strong>, após alguns desses métodos serem executados.</p>
<p>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.</p>
<div class="note">
<p><strong>Nota</strong>: 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. {{HTMLElement("a")}}).</p>
</div>
<p>O comportamento acima é aplicado para as seleções feitas usando os seguintes métodos:</p>
<ul>
<li>{{DOMxRef("Selection.collapse()")}}</li>
<li>{{DOMxRef("Selection.collapseToStart()")}}</li>
<li>{{DOMxRef("Selection.collapseToEnd()")}}</li>
<li>{{DOMxRef("Selection.extend()")}}</li>
<li>{{DOMxRef("Selection.selectAllChildren()")}}</li>
<li>{{DOMxRef("Selection.addRange()")}}</li>
<li>{{DOMxRef("Selection.setBaseAndExtent()")}}</li>
</ul>
<p>e quando o intervalo é modificado usando os seguintes métodos:</p>
<ul>
<li>{{DOMxRef("Range.setStart()")}}</li>
<li>{{DOMxRef("Range.setEnd()")}}</li>
<li>{{DOMxRef("Range.setStartBefore()")}}</li>
<li>{{DOMxRef("Range.setStartAfter()")}}</li>
<li>{{DOMxRef("Range.setEndBefore()")}}</li>
<li>{{DOMxRef("Range.setEndAfter()")}}</li>
<li>{{DOMxRef("Range.collapse()")}}</li>
<li>{{DOMxRef("Range.selectNode()")}}</li>
<li>{{DOMxRef("Range.selectNodeContents()")}}</li>
</ul>
<h3 id="Glossary" name="Glossary">Glossário</h3>
<p>Outras palavras chaves usadas nesta seção.</p>
<dl>
<dt>anchor</dt>
<dd>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.</dd>
<dt>Elemento editável</dt>
<dd>Um elemento editável — i.e. um elemento HTML com o atributo {{htmlattrxref("contenteditable")}} definido, ou o HTML filho de um documento estiver com o {{DOMxRef("Document.designMode", "designMode")}} habilitado.</dd>
<dt>foco de uma seleção</dt>
<dd>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. <strong>Nota:</strong> Não é o mesmo que o elemento selecionado do documento, como retornado em {{DOMxRef("document.activeElement")}}.</dd>
<dt>intervalo</dt>
<dd>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 {{DOMxRef("range")}}. Um objeto de intervalo pode ser criado no DOM e programaticamente adicionada ou removida de uma seleção.</dd>
</dl>
<h2 id="Especificações">Especificações</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName("Selection API", "#selection-interface", "Seleção")}}</td>
<td>{{Spec2("Selection API")}}</td>
<td>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.</td>
</tr>
<tr>
<td>{{SpecName("HTML Editing", "#selection", "Seleção")}}</td>
<td>{{Spec2("HTML Editing")}}</td>
<td>Definição incial (antiga).</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility" name="Browser_compatibility">Compatibilidade de navegadores</h2>
<p>{{Compat("api.Selection")}}</p>
<h2 id="See_also" name="See_also">Veja também</h2>
<ul>
<li>{{DOMxRef("Window.getSelection")}}, {{DOMxRef("Document.getSelection")}}, {{DOMxRef("Range")}}</li>
<li>Selection-related events: {{Event("selectionchange")}} and {{Event("selectstart")}}</li>
<li>HTML inputs provide simpler helper APIs for working with selection (see {{DOMxRef("HTMLInputElement.setSelectionRange()")}})</li>
<li>{{DOMxRef("Document.activeElement")}}, {{DOMxRef("HTMLElement.focus()")}}, and {{DOMxRef("HTMLElement.blur()")}}</li>
</ul>
<h2 id="Notas_da_Gecko">Notas da Gecko</h2>
<ul>
<li>Gecko/Firefox provide additional features, available to chrome (internal and add-on) code only. These are defined in {{Interface("nsISelectionPrivate")}}.</li>
<li>Mozilla source code: {{Source("dom/webidl/Selection.webidl")}}</li>
<li>{{DOMxRef("Selection.selectionLanguageChange()")}}{{Obsolete_Inline("gecko29")}} used to be exposed to the web content until Firefox 29</li>
</ul>
<dl>
</dl>
|
