元素:querySelectorAll() 方法
语法
querySelectorAll(selectors)
参数
selectors
-
包含一个或多个要匹配的选择器的字符串。此字符串必须是有效的 CSS 选择器字符串;如果不是,则会抛出
SyntaxError
异常。请注意,HTML 规范不要求属性值必须是有效的 CSS 标识符。如果
class
或id
属性值不是有效的 CSS 标识符,则必须在选择器中使用它之前对其进行转义,方法是调用CSS.escape()
函数处理该值,或使用 转义字符 中描述的技术之一。请参阅 转义属性值 以了解示例。选择器应用于整个文档,而不仅仅是调用
querySelectorAll()
的特定元素。要将选择器限制为调用querySelectorAll()
的元素,请在选择器开头包含:scope
伪类。请参阅 选择器作用域 示例。
返回值
异常
SyntaxError
DOMException
-
如果指定
selectors
字符串的语法无效,则抛出此异常。
示例
获取所有具有自定义数据值的元素
此示例使用 属性选择器 来选择多个具有包含 "funnel-chart-percent" 的 data-name
数据属性的元素。
<section class="box" id="sect1">
<div data-name="funnel-chart-percent1">10.900%</div>
<div data-name="funnel-chart-percent2">3700.00%</div>
<div data-name="funnel-chart-percent3">0.00%</div>
</section>
const refs = [
...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`),
];
获取匹配项列表
要获取元素 "myBox"
中包含的所有 <p>
元素的 NodeList
。
const matches = myBox.querySelectorAll("p");
此示例返回 "myBox"
中所有类名为 "note
" 或 "alert
" 的 <div>
元素的列表。
const matches = myBox.querySelectorAll("div.note, div.alert");
在这里,我们获取文档中所有 <p>
元素的列表,这些元素的直接父元素是类名为 "highlighted"
的 <div>
,并且位于 ID 为 "test"
的容器内。
const container = document.querySelector("#test");
const matches = container.querySelectorAll("div.highlighted > p");
此示例使用 属性选择器 返回文档中所有包含名为 "data-src"
属性的 <iframe>
元素的列表。
const matches = document.querySelectorAll("iframe[data-src]");
在此,属性选择器用于返回 ID 为 "userlist"
的列表中所有具有 "data-active"
属性且其值为 "1"
的列表项的列表。
const container = document.querySelector("#userlist");
const matches = container.querySelectorAll("li[data-active='1']");
访问匹配项
返回匹配元素的 NodeList
后,您可以像访问任何数组一样检查它。如果数组为空(即,其 length
属性为 0
),则表示未找到任何匹配项。
否则,您可以使用标准数组表示法访问列表的内容。您可以使用任何常见的循环语句,例如
const highlightedItems = userList.querySelectorAll(".highlighted");
highlightedItems.forEach((userItem) => {
deleteUser(userItem);
});
注意:NodeList
不是真正的数组,也就是说它没有像 slice
、some
、map
等数组方法。要将其转换为数组,请尝试 Array.from(nodeList)
。
选择器作用域
querySelectorAll()
方法将其选择器应用于整个文档:它们的作用域不限于调用该方法的元素。要限定选择器的作用域,请在选择器字符串的开头包含 :scope
伪类。
HTML
在此示例中,HTML 包含
- 两个按钮:
#select
和#select-scope
- 三个嵌套的
<div>
元素:#outer
、#subject
和#inner
- 一个
<pre>
元素,示例使用它进行输出。
<button id="select">Select</button>
<button id="select-scope">Select with :scope</button>
<div id="outer">
#outer
<div id="subject">
#subject
<div id="inner">#inner</div>
</div>
</div>
<pre id="output"></pre>
JavaScript
在 JavaScript 中,我们首先选择 #subject
元素。
当按下 #select
按钮时,我们对 #subject
调用 querySelectorAll()
,并将 "#outer #inner"
作为选择器字符串传递。
当按下 #select-scope
按钮时,我们再次对 #subject
调用 querySelectorAll()
,但这次我们传递 ":scope #outer #inner"
作为选择器字符串。
const subject = document.querySelector("#subject");
const select = document.querySelector("#select");
select.addEventListener("click", () => {
const selected = subject.querySelectorAll("#outer #inner");
output.textContent = `Selection count: ${selected.length}`;
});
const selectScope = document.querySelector("#select-scope");
selectScope.addEventListener("click", () => {
const selected = subject.querySelectorAll(":scope #outer #inner");
output.textContent = `Selection count: ${selected.length}`;
});
结果
当我们按下“选择”时,选择器将选择所有 ID 为 inner
且祖先元素 ID 为 outer
的元素。请注意,即使 #outer
在 #subject
元素之外,它仍然用于选择,因此我们找到了 #inner
元素。
当我们按下“使用 :scope 选择”时,:scope
伪类将选择器作用域限制为 #subject
,因此 #outer
不用于选择器匹配,并且我们找不到 #inner
元素。
转义属性值
此示例显示,如果 HTML 文档包含一个 id
不是有效的 CSS 标识符,则必须在 querySelectorAll()
中使用它之前转义属性值。
HTML
在以下代码中,一个 <div>
元素的 id
为 "this?element"
,这不是有效的 CSS 标识符,因为 CSS 标识符不允许使用 "?"
字符。
我们还有三个按钮和一个用于记录错误的 <pre>
元素。
<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
div {
background-color: blue;
margin: 1rem 0;
height: 100px;
width: 200px;
}
JavaScript
所有三个按钮在点击时都会尝试选择 <div>
,然后将其背景颜色设置为随机值。
- 第一个按钮直接使用
"this?element"
值。 - 第二个按钮使用
CSS.escape()
转义该值。 - 第三个按钮使用反斜杠显式转义
"?"
字符。请注意,我们还必须使用另一个反斜杠转义反斜杠本身,例如:"\\?"
。
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 elements = container.querySelectorAll(`#${id}`);
const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
elements[0].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-queryselectorall① |
浏览器兼容性
BCD 表格仅在浏览器中加载