大网数据广告活动
Web 标准与前端开发

document.querySelector()

· 52CE 我爱测

文档对象模型Document引用的 **`querySelector()`** 方法返回文档中与指定选择器或选择器组匹配的第一个 Element对象。如果找不到匹配项,则返回`null`。

DOM

文档对象模型Document引用的 querySelector() 方法返回文档中与指定选择器或选择器组匹配的第一个 Element对象。如果找不到匹配项,则返回null。

[!NOTE] 匹配是使用深度优先先序遍历,从文档标记中的第一个元素开始,并按子节点的顺序依次遍历。

语法

element = document.querySelector(selectors);

参数

  • selectors
    • : 包含一个或多个要匹配的选择器的字符串。该字符串必须是有效的 CSS 选择器字符串;如果不是,则抛出 SYNTAX_ERR 异常。请参阅使用选择器定位 DOM 元素以获取有关选择器以及如何管理它们的更多信息。

[!NOTE] 必须使用反斜杠字符转义不属于标准 CSS 语法的字符。由于 JavaScript 也使用退格转义,因此在使用这些字符编写字符串文字时必须特别小心。有关详细信息,请参阅转义特殊字符。

返回值

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

如果你需要与指定选择器匹配的所有元素的列表,则应该使用 Document.querySelectorAll。

异常

  • SYNTAX_ERR
    • : 指定selectors的语法无效。

注意

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

CSS 伪类不会返回任何元素,见 Selectors API 中的相关规定。

转义特殊字符

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

<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
  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
</script>

示例

查找第一个匹配 class 属性的 html 元素

这个例子中,会返回当前文档中第一个类名为 "myclass" 的元素:

var el = document.querySelector(".myclass");

一个更复杂的选择器

选择器也可以非常强大,如以下示例所示.

这里,一个 class 属性为"user-panel main"的 div 元素div(<div class="user-panel main">) 内包含一个 name 属性为"login"的 input 元素input (<input name="login"/>) ,如何选择,如下所示:

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

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。