Element: querySelectorAll() メソッド
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Element
の querySelectorAll()
メソッドは、静的な (ライブではない) NodeList
で、メソッド呼び出しの時点でそのオブジェクトの子孫にあたる要素のうち、一連のセレクターに一致するもののリストを返します。
構文
querySelectorAll(selectors)
引数
selectors
-
照合する 1 つまたは複数のセレクターを含む文字列です。この文字列は妥当な CSS セレクターでなければならず、そうでない場合は
SyntaxError
例外が発生します。セレクターの仕様と要素の識別の詳細は、セレクターを使用した DOM 要素の指定を参照してください。複数のセレクターを指定する際は、カンマで区切ります。なお、セレクターは
querySelectorAll()
が呼ばれた特定の要素だけでなく、文書全体に適用されることに注意してください。セレクターをquerySelectorAll()
が呼び出された要素に限定するには、セレクターの最初に:scope
擬似クラスを記述してください。セレクターのスコープの例を参照してください。
メモ: 標準の CSS 構文の一部ではない文字は、バックスラッシュ文字を使ってエスケープしなければなりません。 JavaScript でもバックスラッシュによるエスケープが使われているため、これらの文字を使った文字列リテラルを記述する際は、特に注意する必要があります。詳細は特殊文字のエスケープを参照してください。
返値
例外
SyntaxError
DOMException
-
指定された
selectors
の構文が妥当ではない場合に発生します。
例
データセットセレクターと属性セレクター
<section class="box" id="sect1">
<div class="funnel-chart-percent1">10.900%</div>
<div class="funnel-chart-percent2">3700.00%</div>
<div class="funnel-chart-percent3">0.00%</div>
</section>
// データセットセレクター
const refs = [
...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`),
];
// 属性セレクター
// const refs = [...document.querySelectorAll(`[class*="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class^="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class$="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class~="funnel-chart-percent"]`)];
一致するもののリストの入手
NodeList
で "myBox"
要素の中にあるすべての <p>
要素を取得するには、次のようにします。
const matches = myBox.querySelectorAll("p");
次の例では、文書内にあるすべての <div>
要素のうち、 "note
" または "alert
" のいずれかのクラスを持つもののリストを返します。
const matches = myBox.querySelectorAll("div.note, div.alert");
ここでは、文書の <p>
要素のうち、直接の親要素が <div>
の "highlighted"
クラスのものであり、それが ID が "test"
であるコンテナーの中にあるものの一覧を取得します。
const container = document.querySelector("#test");
const matches = container.querySelectorAll("div.highlighted > p");
次の例では属性セレクターを使用して、文書内の <iframe>
要素のうち "data-src"
という名前の属性を持つもののリストを返します。
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 に次のものが含まれています。
- 2 つのボタン:
#select
および#select-scope
- 3 重に入れ子になった
<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
ボタンが押されたら、セレクター文字列として "#outer #inner"
を渡して #subject
に対して querySelectorAll()
を呼び出します。
#select-scope
ボタンが押されたら、再び querySelectorAll()
を #subject
に対して呼び出しますが、この時は ":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}`;
});
結果
"Select" を押すと、セレクターは inner
という ID を持つ要素のうち、outer
という ID を持つ祖先を持つ要素をすべて選択します。なお、#outer
は #subject
要素の外側にあるにもかかわらず、選択で使用されるため、#inner
要素が見つかります。
"Select with :scope" を押すと、:scope
擬似クラスがセレクターのスコープを #subject
に制限するので、セレクターの照合では #outer
は使われず、#inner
要素は見つかりません。
仕様書
Specification |
---|
DOM Standard # ref-for-dom-parentnode-queryselectorall① |
ブラウザーの互換性
BCD tables only load in the browser