Document.querySelectorAll()

Document の querySelectorAll() メソッドは、与えられた CSS セレクターに一致する文書中の要素のリストを示す静的な (ライブではない) NodeList を返します。

selectors

DOMString で、照合対象となる 1 つまたは複数のセレクターを含みます。この文字列は妥当な CSS セレクターでなければならず、そうでない場合は SyntaxError 例外が発生します。セレクターの仕様と要素の識別の詳細は、セレクターを使用した DOM 要素の指定を参照してください。複数のセレクターは、カンマで区切って指定することができます。

ライブではない NodeList で、指定されたセレクターの少なくとも 1 つに一致する要素ごとに Element を一つずつ含みます。または一致するものがなければ空の NodeList です。

SyntaxError

指定された selectors の構文が妥当ではない場合です。

文書内のすべての <p> 要素の NodeList を入手します。

const matches = document.querySelectorAll("p");

次の例では、文書内にあるすべての <div> 要素のうち、 note または alert のいずれかのクラスを持つものリストを返します。

const matches = document.querySelectorAll("div.note, div.alert");

次に、 <p> 要素ののうち直近の親要素が test という ID を持つコンテナー内に位置し、直接の親要素が highlighted クラスを持つ <div> であるリストを取得します。

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(function(userItem) {
  deleteUser(userItem);
});

querySelectorAll() は、最も一般的な JavaScript DOM ライブラリーと異なる動作を持ち、意図しない結果をもたらすことがあります。

次の、入れ子になった 3 つの <div> ブロックを持つ HTML について検討します。

<div class="outer">
  <div class="select">
    <div class="inner">
    </div>
  </div>
</div>

const select = document.querySelector('.select');
const inner = select.querySelectorAll('.outer .inner');
inner.length; // 1 です。0 ではありません!

この例で、.outer .inner を<div> に select クラスがついたコンテキストで選択する場合、.outer が検索が行われる基底要素 (.select) の子孫ではないにもかかわらず、.inner クラスの要素が見つかります。既定では、querySelectorAll() はセレクターの最後の要素のみを、検索スコープ内にあるかどうか検証します。

:scope 擬似クラスを使うと、基準となる要素の子孫だけが一致するようになり、期待される挙動を取り戻すことができます。

const select = document.querySelector('.select');
const inner = select.querySelectorAll(':scope .outer .inner');
inner.length; // 0

• セレクターを使用した DOM 要素の指定
• CSS ガイドの[属性セレクター]
• MDN 学習領域の[属性セレクター]
• Element.querySelector() および Element.querySelectorAll()
• Document.querySelector()
• DocumentFragment.querySelector() (en-US) および DocumentFragment.querySelectorAll() (en-US)