元素:querySelector() 方法

querySelector()Element 接口的方法,它返回调用该方法的元素的后代中与指定选择器组匹配的第一个元素。

语法

js
querySelector(selectors)

参数

selectors

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

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

返回值

返回与指定 selectors 组匹配的 baseElement 的第一个后代元素。在匹配时会考虑元素的整个层次结构,包括 baseElement 及其后代元素集之外的元素;换句话说,selectors 首先应用于整个文档,而不是 baseElement,以生成潜在元素的初始列表。然后检查生成的元素是否为 baseElement 的后代。querySelector() 方法返回这些剩余元素中的第一个匹配项。

如果未找到匹配项,则返回的值为 null

异常

SyntaxError DOMException

如果指定的 selectors 无效,则抛出此异常。

示例

让我们考虑一些示例。

查找具有特定属性值的特定的元素

在本例中,返回 HTML 文档正文中第一个类型为空或类型为“text/css”的 <style> 元素。

js
const el = document.body.querySelector(
  "style[type='text/css'], style:not([type])",
);

使用 :scope 伪类获取直接后代

此示例使用 :scope 伪类来检索 parentElement 元素的直接子元素。

HTML

html
<div>
  <h6>Page Title</h6>
  <div id="parent">
    <span>Love is Kind.</span>
    <span>
      <span>Love is Patient.</span>
    </span>
    <span>
      <span>Love is Selfless.</span>
    </span>
  </div>
</div>

CSS

css
span {
  display: block;
  margin-bottom: 5px;
}
.red span {
  background-color: red;
  padding: 5px;
}

JavaScript

js
const parentElement = document.querySelector("#parent");
let allChildren = parentElement.querySelectorAll(":scope > span");
allChildren.forEach((item) => item.classList.add("red"));

结果

整个层次结构计数

此示例演示了在应用 selectors 时会考虑整个文档的层次结构,以便在查找匹配项时仍然会考虑指定 baseElement 之外的层级。

HTML

html
<div>
  <h5>Original content</h5>
  <p>
    inside paragraph
    <span>inside span</span>
    inside paragraph
  </p>
</div>
<div>
  <h5>Output</h5>
  <div id="output"></div>
</div>

JavaScript

js
const baseElement = document.querySelector("p");
document.getElementById("output").textContent =
  baseElement.querySelector("div span").textContent;

结果

结果如下所示

请注意,即使 baseElement 的子节点不包含 <div> 元素(它仍然是指定选择器的一部分),"div span" 选择器仍然成功匹配了 <span> 元素。

转义属性值

此示例显示,如果 HTML 文档包含一个不是有效 CSS 标识符id,则必须在 querySelector() 中使用它之前转义属性值。

HTML

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

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

html
<div id="container">
  <div id="this?element"></div>
</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 container = document.querySelector("#container");
const log = document.querySelector("#log");

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

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

  try {
    const element = container.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");
});

结果

单击第一个按钮会产生错误,而第二个和第三个按钮可以正常工作。

更多示例

有关 selectors 的正确格式的更多示例,请参阅 Document.querySelector()

规范

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

浏览器兼容性

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

另请参阅