Document: querySelector() 方法

querySelector() 方法是 Document 接口中的一个方法，用于返回文档中与指定 CSS 选择器 或 CSS 选择器组匹配的第一个 Element。如果未找到匹配项，则返回 null。

匹配是通过对文档节点进行深度优先前序遍历来完成的，从文档标记中的第一个元素开始，并按子节点数量的顺序迭代遍历后续节点。

如果指定的 selector 匹配一个在文档中被错误使用多次的 ID，则返回第一个具有该 ID 的元素。

根据 Selectors API 的规定，CSS 伪元素 永远不会返回任何元素。

语法

js
querySelector(selectors)

参数

selectors

包含一个或多个要匹配的选择器的字符串。此字符串必须是有效的 CSS 选择器字符串；如果不是，则会抛出 SyntaxError 异常。

请注意，HTML 规范不要求属性值是有效的 CSS 标识符。如果 class 或 id 属性值不是有效的 CSS 标识符，则必须在选择器中使用它之前对其进行转义，方法是调用 CSS.escape() 方法对该值进行转义，或者使用 转义字符 中描述的技术之一。有关示例，请参阅 转义属性值。

返回值

表示文档中与指定 CSS 选择器 组匹配的第一个元素的 Element 对象，如果未找到匹配项，则返回 null。

如果您需要与指定选择器匹配的所有元素列表，则应使用 querySelectorAll() 方法。

异常

SyntaxError DOMException

如果指定的 selectors 语法无效，则抛出此异常。

示例

查找与类匹配的第一个元素

在本例中，将返回文档中具有类“myclass”的第一个元素

js
const el = document.querySelector(".myclass");

复杂选择器

选择器还可以非常强大，如下例所示。在此，将返回文档中位于具有类“user-panel main” (<div class="user-panel main">) 的 <div> 内部的具有名称“login” (<input name="login"/>) 的第一个 <input> 元素

js
const el = document.querySelector("div.user-panel.main input[name='login']");

否定

由于所有 CSS 选择器字符串都有效，因此您也可以否定选择器

js
const el = document.querySelector(
  "div.user-panel:not(.main) input[name='login']",
);

这将选择一个父 div 具有 user-panel 类但没有 main 类的 input。

转义属性值

此示例说明了如果 HTML 文档包含一个 id，它不是有效的 CSS 标识符，那么我们必须在 querySelector() 中使用该属性值之前对其进行转义。

HTML

在以下代码中，一个 <div> 元素的 id 为 "this?element"，它不是有效的 CSS 标识符，因为 "?" 字符在 CSS 标识符中不允许。

我们还有三个按钮和一个 <pre> 元素用于记录错误。

html
<div id="this?element"></div>

<button id="no-escape">No escape</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">Manual escape</button>

<pre id="log"></pre>

CSS

css
div {
  background-color: blue;
  margin: 1rem 0;
  height: 100px;
  width: 200px;
}

JavaScript

所有三个按钮在点击时都尝试选择 <div>，然后将其背景颜色设置为随机值。

  • 第一个按钮直接使用 "this?element" 值。
  • 第二个按钮使用 CSS.escape() 对该值进行转义。
  • 第三个按钮使用反斜杠显式地转义 "?" 字符。请注意，我们还必须使用另一个反斜杠来转义反斜杠本身，例如："\\?"。
js
const log = document.querySelector("#log");

function random(number) {
  return Math.floor(Math.random() * number);
}

function setBackgroundColor(id) {
  log.textContent = "";

  try {
    const element = document.querySelector(`#${id}`);
    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
    element.style.backgroundColor = randomColor;
  } catch (e) {
    log.textContent = e;
  }
}

document.querySelector("#no-escape").addEventListener("click", () => {
  setBackgroundColor("this?element");
});

document.querySelector("#css-escape").addEventListener("click", () => {
  setBackgroundColor(CSS.escape("this?element"));
});

document.querySelector("#manual-escape").addEventListener("click", () => {
  setBackgroundColor("this\\?element");
});

结果

点击第一个按钮会报错，而第二个和第三个按钮则正常工作。

规范

规范
DOM 标准
# ref-for-dom-parentnode-queryselector①

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参见