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
|
---
title: Document.querySelector()
slug: Web/API/Document/querySelector
tags:
- API
- DOM
- Document
- Elementos DOM
- Referencia
- Selector API
- Seletores CSS
- Seletors
- metodo
- querySelector
translation_of: Web/API/Document/querySelector
---
<div>{{ApiRef("DOM")}}</div>
<p>O método <code><strong>querySelector()</strong></code> de {{domxref("Document")}} retorna o primeiro {{domxref("Element")}} dentro do documento que corresponde ao seletor, ou grupo de seleteores especificados. Se não há elementos que correspondem, <code>null</code> é devolvido como resultado.</p>
<div class="note">
<p><strong>Nota</strong>: A correspondência é feita através de uma travessia <em>pre-order</em> em profundidade dos nódulos do documento, a começar com o primeiro elemento da marcação do documento e iterando através de nódulos sequenciais por ordem do número de nódulos filhos.</p>
</div>
<h2 id="Syntaxe">Syntaxe</h2>
<pre class="syntaxbox notranslate"><var>element</var> = document.querySelector(<var>selectors</var>);
</pre>
<h3 id="Parameteros">Parameteros</h3>
<dl>
<dt><var>selectors</var></dt>
<dd>Um {{domxref("DOMString")}} a conter um ou mais seletores para com que corresponder. Esta string tem de ser um seletor de CSS valido; se não é, uma <em>exception</em> <code>SYNTAX_ERR</code> é lançada. Veja <a href="/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors">Localizar elementos do DOM a usar seletores</a> para saber mais sobre seletor e como os gerir.</dd>
</dl>
<div class="note">
<p><strong>Nota:</strong> Os carateres que não fazem parte da sintaxe padrão do CSS devem ser evitados ao usar um caráter de barra invertida. Uma vez que o JavaScript também usa barra invertida para escapar, deve ter especial cuidado ao escrever <em>string literals</em> usando estes carateres. Veja {{anch("Escapar carateres especiais")}} para obter mais informação.</p>
</div>
<h3 id="Resultado">Resultado</h3>
<p>Um objeto {{domxref("HTMLElement")}} a representar o primeiro elemento no documento que corresponde aos <a href="/en-US/docs/Web/CSS/CSS_Selectors">seletores de CSS</a>, ou <code>null</code> se não há elementos correspondentes.</p>
<p>Se precisar de uma lista de todos os elementos que correspondem ao seletores especificados, deve usar {{domxref("Document.querySelectorAll", "querySelectorAll()")}}.</p>
<h3 id="Exeções">Exeções</h3>
<dl>
<dt><code>SYNTAX_ERR</code></dt>
<dd>O syntaxe dos <em>selectors</em> especificados está incorrecto.</dd>
</dl>
<h2 id="Notas_de_uso">Notas de uso</h2>
<p>Se o seletor especificado corresponde a um ID que é incorretamente utilizado mais que uma vez num documento, o primeiro elemento com esse ID será devolvido.</p>
<p><a href="/en-US/docs/Web/CSS/Pseudo-elements">Pseudoelementos de CSS</a> não devolvem elementos, como é especificado na <a href="http://www.w3.org/TR/selectors-api/#grammar">API de seletores</a>.</p>
<h3 id="Escapar_carateres_especiais">Escapar carateres especiais</h3>
<p>Para corresponder a um ID ou seletor que não segue a sintaxe de CSS padrão (ao usar o caráter de dois pontos ou espaço incorretamente), deve escapar o caráter com uma barra invertida ("<code>\</code>"). Como a barra invertida também é um caráter de escapar no JavaScript, se a escrever numa <em>string literal</em>, tem de a escapar duas vezes (primeiro para a <em>string</em> do JavaScript, e depois para o <code>querySelector()</code>):</p>
<pre class="brush: html notranslate"><div id="foo\bar"></div>
<div id="foo:bar"></div>
<script>
console.log('#foo\bar'); // "#fooar" (\b é o caráter de controlo para a barra invertida)
document.querySelector('#foo\bar'); // Corresponde a nada
console.log('#foo\\bar'); // "#foo\bar"
console.log('#foo\\\\bar'); // "#foo\\bar"
document.querySelector('#foo\\\\bar'); // Corresponde ao primeiro div
document.querySelector('#foo:bar'); // Corresponde a nada
document.querySelector('#foo\\:bar'); // Corresponde ao segundo div
</script></pre>
<h2 id="Exemplos">Exemplos</h2>
<h3 id="Encontrar_o_primeiro_elemento_que_corresponde_a_uma_classe">Encontrar o primeiro elemento que corresponde a uma classe</h3>
<p>Neste exemplo, o primeiro elemento no documento com a classe <code>myclass</code> é devolvida:</p>
<pre class="brush: js notranslate">var el = document.querySelector(".myclass");
</pre>
<h3 id="Um_seletor_mais_complexo">Um seletor mais complexo</h3>
<p>Seletores são muito poderosos, como demonstrado no seguinte exemplo. O primeiro elemento {{HTMLElement("input")}} com o nome "login" (<code><input name="login"/></code>) encontrado dentro dum {{HTMLElement("div")}} cuja classe é "user-panel main" (<code><div class="user-panel main"></code>) no documento é devolvido:</p>
<pre class="brush: js notranslate">var el = document.querySelector("div.user-panel.main input[name='login']");
</pre>
<h3 id="Negação">Negação</h3>
<p>Todos os strings de seletores de CSS são válidos, assim também é possivel ter seletores de negação:</p>
<pre class="brush: js notranslate">var el = document.querySelector("div.user-panel:not(.main) input[name='login']");</pre>
<p>Isto seléciona um <code>input</code> que tem um <code>div</code> com classe <code>user-panel</code> como parente, mas sem a classe <code>main</code>.</p>
<h2 id="Especificações">Especificações</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Especificação</th>
<th scope="col">Estado</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName("DOM WHATWG", "#dom-parentnode-queryselector", "document.querySelector()")}}</td>
<td>{{Spec2("DOM WHATWG")}}</td>
</tr>
</tbody>
</table>
<h2 id="Compatibilidade">Compatibilidade</h2>
<div>{{Compat("api.Document.querySelector")}}</div>
<h2 id="Veja_também">Veja também</h2>
<ul>
<li><a href="/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors">Localizar elementos DOM a usar selectors</a></li>
<li>{{domxref("Element.querySelector()")}}</li>
<li>{{domxref("Document.querySelectorAll()")}}</li>
<li>{{domxref("Element.querySelectorAll()")}}</li>
<li><a href="/en-US/docs/Code_snippets/QuerySelector">Snippets de código para o querySelector</a></li>
</ul>
|
