element.querySelectorAll
Element
の querySelectorAll()
メソッドは対象要素の子孫の内、与えられた CSS セレクターに一致する要素リストを示す静的な(生きていない) NodeList
を返します(起点となる要素は、たとえマッチしていても含まれません)。
注: このメソッドは ParentNode
ミックスインの querySelectorAll()
メソッドを元に実装されています。
構文
elementList = parentNode.querySelectorAll(selectors);
引数
selectors
- マッチのための 1 つまたは複数のセレクターを含む
DOMString
です。この文字列は妥当な CSS セレクター文字列でなければならず、そうでない場合はSyntaxError
例外がスローされます。セレクターの仕様と要素の識別の詳細は、セレクターを使用した DOM 要素の特定を参照してください。複数のセレクターを指定する際は、カンマで区切ります。
注: 標準の CSS 構文の一部ではない文字は、バックスラッシュ文字を使ってエスケープしなければなりません。 JavaScript でもバックスラッシュによるエスケープが使われているため、これらの文字を使った文字列リテラルを記述する際は、特に注意する必要があります。詳細は特殊文字のエスケープを参照してください。
戻り値
指定されたセレクターのうち1つ以上にマッチする Element
オブジェクトを含んだ非ライブな NodeList
です。
メモ: 指定した selectors
にCSS 疑似要素が含まれている場合、返されるリストは常に空になります。
例外
SyntaxError
- 指定した
selectors
の構文が妥当ではない。
例
dataset セレクターと属性セレクター
<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>
// dataset セレクター
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"]`)];
一致のリストを入手する
次の例では、myBox
要素の中に存在するすべての <p>
要素の NodeList
を取得しています。
var matches = myBox.querySelectorAll("p");
次の例では、mybox
内にある note
または alert
のいずれかのクラスを持つ、すべての <div>
要素のリストを返します。
var matches = myBox.querySelectorAll("div.note, div.alert");
次の例では、test
という ID を持つコンテナー内に位置し、直接の親要素が highlighted
のクラスを持つ div
である p
要素のリストを取得します。
var container = document.querySelector("#test");
var matches = container.querySelectorAll("div.highlighted > p");
次の例では、属性セレクターを使って、文書内にある、 data-src
属性を持つ文書内の iframe
要素のリストを返します。
var matches = domument.querySelectorAll("iframe[data-src]");
次の例では、属性セレクターを使って、「ID が userlist
である要素内の、data-active
属性を持ち、その値が 1
である要素群」のリストを返します。
var container = document.querySelector("#userlist");
var matches = container.querySelectorAll("li[data-active='1']");
一致したリストへアクセスする
一旦、一致した要素の NodeList
} が返されると、それをちょうど配列のように試すことができます。配列が空である (length
プロパティが 0 である) 場合は、一致がなかったということです。
それ以外の場合は、単純に標準の配列表記を使って、リストの内容にアクセスすることができます。次のように、任意の一般的なループ処理を使うことができます。
var highlightedItems = userList.querySelectorAll(".highlighted");
highlightedItems.forEach(function(userItem) {
deleteUser(userItem);
});
注: NodeList は純正な配列ではないので、slice, some, map などのArray メソッドを持っていません。Array.from(nodeList) を使うことで純正の配列に変換することができます。
特殊な例
querySelectorAll()
は、最も一般的な JavaScript DOM ライブラリと異なる動作を持ち、意図しない結果をもたらすことがあります。
HTML
次の、入れ子になった 3 つの <div>
ブロックを持つ HTML について検討します。
<div class="outer">
<div class="select">
<div class="inner">
</div>
</div>
</div>
JavaScript
var select = document.querySelector('.select');
var inner = select.querySelectorAll('.outer .inner');
inner.length; // 1, not 0!
この例では、"select"
class を持つ <div>
の文脈で ".outer .inner"
を選択するとき、.outer
が基準となる要素(.select
で検索される)の子孫ではないにもかかわらず、".inner"
class を持つ要素が見つけられています。querySelectorAll()
はデフォルトでは、セレクターの最後の要素が検索スコープに含まれているかどうかのみ検証します。
:scope
擬似クラスを使うと、基準となる要素の子孫だけが一致するようになり、期待される挙動を取り戻すことができます。
var select = document.querySelector('.select');
var inner = select.querySelectorAll(':scope .outer .inner');
inner.length; // 0
仕様
仕様書 | 策定状況 | コメント |
---|---|---|
DOM ParentNode.querySelectorAll() の定義 |
現行の標準 | Living standard |
Selectors API Level 2 ParentNode.querySelectorAll() の定義 |
廃止 | 変更なし |
DOM4 ParentNode.querySelectorAll() の定義 |
廃止 | 初期定義 |
Selectors API Level 1 querySelectorAll の定義 |
廃止 | 初期定義 |
ブラウザー実装状況
BCD tables only load in the browser