path: root/files/zh-cn/web/api/document/queryselector/index.html

---
title: document.querySelector()
slug: Web/API/Document/querySelector
tags:
  - API
  - CSS选择器
  - DOM
  - querySelector
  - 文档对象模型Document
translation_of: Web/API/Document/querySelector
---
<div>{{ ApiRef("DOM") }}</div>

<p>文档对象模型{{domxref("Document")}}引用的<code><strong>querySelector()</strong></code>方法返回文档中与指定选择器或选择器组匹配的第一个 {{domxref("Element")}}对象。 如果找不到匹配项，则返回<code>null</code>。</p>

<div class="note">
<p><strong>提示</strong>: 匹配是使用深度优先先序遍历，从文档标记中的第一个元素开始，并按子节点的顺序依次遍历。</p>
</div>

<h2 id="Syntax" name="Syntax">语法</h2>

<pre class="brush: js notranslate">element = document.querySelector(selectors);</pre>

<h3 id="参数">参数</h3>

<dl>
 <dt><code>selectors</code></dt>
 <dd>包含一个或多个要匹配的选择器的 DOM字符串{{domxref("DOMString")}}。 该字符串必须是有效的CSS选择器字符串；如果不是，则引发<code>SYNTAX_ERR</code>异常。请参阅<a href="/zh-CN/docs/Web/API/Document_Object_Model/Locating_DOM_elements_using_selectors">使用选择器定位DOM元素</a>以获取有关选择器以及如何管理它们的更多信息。</dd>
</dl>

<div class="note">
<p><strong>提示:</strong>必须使用反斜杠字符转义不属于标准CSS语法的字符。 由于JavaScript也使用退格转义，因此在使用这些字符编写字符串文字时必须特别小心。 有关详细信息，请参阅{{anch("Escaping special characters")}}。</p>
</div>

<h3 id="返回值">返回值</h3>

<p>表示文档中与指定的一组CSS选择器匹配的第一个元素,一个 {{domxref("Element")}}对象。如果没有匹配到，则返回null。</p>

<p>如果您需要与指定选择器匹配的所有元素的列表，则应该使用{{domxref("Document.querySelectorAll", "querySelectorAll()")}} 。</p>

<h3 id="异常">异常</h3>

<dl>
 <dt><code>SYNTAX_ERR</code></dt>
 <dd>指定<code>selectors</code>的语法无效。</dd>
</dl>

<h2 id="Notes" name="Notes">注意</h2>

<p>如果选择器是一个 ID，并且这个 ID 在文档中错误地使用了多次，那么返回第一个匹配该 ID 的元素。</p>

<p>CSS 伪类不会返回任何元素，见 <a href="https://www.w3.org/TR/selectors-api/#grammar">Selectors API</a> 中的相关规定。</p>

<h3 id="转义特殊字符">转义特殊字符</h3>

<p>如果要匹配的ID或选择器不符合 CSS 语法（比如不恰当地使用了冒号或者空格），你必须用反斜杠将这些字符转义。由于 JavaScript 中，反斜杠是转义字符，所以当你输入一个文本串时，你必须将它转义两次（一次是为 JavaScript 字符串转义，另一次是为 <code>querySelector</code> 转义）：</p>

<pre class="brush: html notranslate">&lt;div id="foo\bar"&gt;&lt;/div&gt;
&lt;div id="foo:bar"&gt;&lt;/div&gt;

&lt;script&gt;
  console.log('#foo\bar')               // "#fooar"
  document.querySelector('#foo\bar')    // 不匹配任何元素

  console.log('#foo\\bar')              // "#foo\bar"
  console.log('#foo\\\\bar')            // "#foo\\bar"
  document.querySelector('#foo\\\\bar') // 匹配第一个div

  document.querySelector('#foo:bar')    // 不匹配任何元素
  document.querySelector('#foo\\:bar')  // 匹配第二个div
&lt;/script&gt;
</pre>

<h2 id="示例">示例</h2>

<h3 id="查找第一个匹配_class属性的html元素">查找第一个匹配 class属性的html元素</h3>

<p>这个例子中，会返回当前文档中第一个类名为 "<code>myclass</code>" 的元素：</p>

<pre class="brush: js notranslate">var el = document.querySelector(".myclass");</pre>

<h3 id="一个更复杂的选择器">一个更复杂的选择器</h3>

<p><em>选择器也可以非常强大，如以下示例所示</em>.</p>

<p>这里, 一个class属性为"user-panel main"的div元素{{HTMLElement("div")}}(<code>&lt;div class="user-panel main"&gt;</code>)内包含一个name属性为"login"的input元素{{HTMLElement("input")}} (<code>&lt;input name="login"/&gt;</code>) ，如何选择，如下所示:</p>

<pre class="brush: js notranslate">var el = document.querySelector("div.user-panel.main input[name='login']");</pre>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">技术规范</th>
   <th scope="col">状态</th>
   <th scope="col">说明</th>
  </tr>
  <tr>
   <td>{{SpecName("Selectors API Level 2", "#interface-definitions", "document.querySelector()")}}</td>
   <td>{{Spec2("Selectors API Level 2")}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName("Selectors API Level 1", "#interface-definitions", "document.querySelector()")}}</td>
   <td>{{Spec2("Selectors API Level 1")}}</td>
   <td>初稿</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_Compatibility" name="Browser_Compatibility">浏览器兼容性</h2>

<p>{{Compat("api.Document.querySelector")}}</p>

<h2 id="See_also" name="See_also">相关链接</h2>

<ul>
 <li><a href="/zh-CN/docs/Web/API/Document_Object_Model/Locating_DOM_elements_using_selectors">Locating DOM elements using selectors</a></li>
 <li>{{domxref("Element.querySelector()")}}</li>
 <li>{{domxref("Document.querySelectorAll()")}}</li>
 <li>{{domxref("Element.querySelectorAll()")}}</li>
</ul>