Element: querySelector() メソッド

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.

querySelector() は Element インターフェイスのメソッドで、呼び出された要素の子孫要素の中で、指定されたセレクター群に一致する最初の要素を返します。

構文

js
querySelector(selectors)

引数

selectors

照合する 1 つ以上のセレクターの入った文字列です。この文字列は、有効な CSS セレクターの文字列でなければなりません。そうでない場合は SyntaxError 例外が発生します。

HTML 仕様では、属性値が有効な CSS 識別子であることを求めていないことに注意してください。 class または id 属性の値が有効な CSS 識別子でない場合は、セレクターで使用する前に、値に対して CSS.escape() で呼び出してエスケープするか、または「文字エスケープ」で記述されているテクニックのいずれかを使用してエスケープする必要があります。例えば、「属性値のエスケープ」を参照してください。

返値

baseElement の子孫要素のうち、 selectors で指定されたセレクター群に一致するものを返します。照合の際には、 baseElement とその子孫を含む要素群の外にあるものも含めて、要素の階層全体を考慮します。言い換えると、 selectors はまず baseElement ではなく、文書全体に適用され、候補となる要素の初期リストが生成されます。その結果得られた要素が、 baseElement の子孫であるかどうかが調べられます。それらの残りの要素のうち、最初に一致したものが querySelector() メソッドによって返されます。

一致するものが見つからなかったら、返値は null になります。

例外

SyntaxError DOMException

指定された selectors が無効であった場合に発生します。

例

いくつかの例を検討してみましょう。

属性に特定の値を持つ特定の要素を探す

この最初の例では、 HTML 文書の本文内で type 属性がないか、 type 属性が "text/css" である要素のうち最初のものを返します。

js
const el = document.body.querySelector(
  "style[type='text/css'], style:not([type])",
);

:scope 擬似クラスを使用して直接の子を取得

この例では :scope 擬似クラスを使用して、 parentElement 要素の直接の子を取得します。

HTML

html
<div>
  <h6>ページタイトル</h6>
  <div id="parent">
    <span>愛は情け深い。</span>
    <span>
      <span>愛は忍耐強い。</span>
    </span>
    <span>
      <span>愛は見返りを求めない。</span>
    </span>
  </div>
</div>

CSS

css
span {
  display: block;
  margin-bottom: 5px;
}
.red span {
  background-color: red;
  padding: 5px;
}

JavaScript

js
const parentElement = document.querySelector("#parent");
let allChildren = parentElement.querySelectorAll(":scope > span");
allChildren.forEach((item) => item.classList.add("red"));

結果

全体の階層数

この例では、 selectors を適用する際に、文書全体の階層を考慮することを示しています。そのため、位置を照合する際には、指定した baseElement 以外のレベルも考慮されることになります。

HTML

html
<div>
  <h5>オリジナルコンテンツ</h5>
  <p>
    内部の段落
    <span>内部の span</span>
    内部の段落
  </p>
</div>
<div>
  <h5>出力</h5>
  <div id="output"></div>
</div>

JavaScript

js
const baseElement = document.querySelector("p");
document.getElementById("output").textContent =
  baseElement.querySelector("div span").textContent;

結果

結果は次のようになります。

"div span" セレクターは、 baseElement の子ノードが <div> 要素を含んでいなくても、 <span> 要素に一致することに注目してください（これはまだ指定したセレクターに含まれています）。

属性値のエスケープ

例えば、 HTML 文書の中の id が有効な CSS 識別子ではないものが含まれている場合、 querySelector() で使用する前に属性値をエスケープする必要があります。

HTML

以下のコードは、 <div> 要素には id として "this?element" が設定されており、これは有効な CSS 識別子ではありません。 "?" 文字が CSS 識別子に許可されていないためです。

ここには 3 つのボタンがあり、エラーを出力するために <pre> 要素があります。

html
<div id="container">
  <div id="this?element"></div>
</div>

<button id="no-escape">エスケープなし</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">手動エスケープ</button>

<pre id="log"></pre>

CSS

css
div {
  background-color: blue;
  margin: 1rem 0;
  height: 100px;
  width: 200px;
}

JavaScript

3 つのボタンはどれも、クリックすると、 <div> を選択して、その背景色をランダムな値に設定しようとします。

  • 最初のボタンは "this?element" の値を直接使用しています。
  • 2 つ目のボタンは CSS.escape() で値をエスケープします。
  • 3 つ目のボタンはバックスラッシュを用いて、明示的に "?" 文字をエスケープしています。なお、もう一つのバックスラッシュを用いて、 "\\?" のようにバックスラッシュ自体をエスケープする必要があります。
js
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 element = container.querySelector(`#${id}`);
    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
    element.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");
});

結果

最初のボタンをクリックするとエラーが返されますが、 2 つ目と 3 つ目のボタンは正規に動作します。

それ以外の例

selectors の適切な書式について、その他の例は Document.querySelector() を参照してください。

仕様書

Specification
DOM
# ref-for-dom-parentnode-queryselectorall①

ブラウザーの互換性

BCD tables only load in the browser

関連情報