Document.querySelector()

Document の querySelector() メソッドは、指定されたセレクターまたはセレクターのグループに一致する、文書内の最初の Element を返します。一致するものが見つからない場合は null を返します。

構文

element = document.querySelector(selectors);

引数

selectors

1つまたは複数のセレクターを含む DOMString。この文字列は妥当な CSS セレクターでなければならず、そうでない場合は SYNTAX_ERR が投げられます。セレクターとその管理の方法の詳細について、セレクターを使用した DOM 要素の指定を参照してください。

返値

文書内で指定された CSS セレクターに最初に一致する要素を示す HTMLElement オブジェクト、もしくは、一致する要素がない場合は null を返します。

指定されたセレクターに一致するすべての要素のリストが必要な場合は、代わりに querySelectorAll() を使用してください。

例外

SYNTAX_ERR

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

使用上のメモ

指定されたセレクターが、誤って文書内で複数回使われている ID に一致する場合は、その ID を持つ最初の要素が返されます。

CSS 擬似要素は Selectors API で策定されている通り、何も要素を返しません。

特殊文字のエスケープ

標準の CSS の構文に従っていない ID やセレクター (例えば、コロンやスペースを不適切に使用しているもの) で一致させるためには、バックスラッシュ ("\") でその文字をエスケープしなければなりません。バックスラッシュは JavaScript のエスケープ文字でもあるので、文字列リテラルを入力する場合、それを2回エスケープする必要があります (1回目は JavaScript の文字列のため、2回目は querySelector() のため)。

<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
  console.log('#foo\bar');               // "#fooar" (\b はバックスペース制御文字)
  document.querySelector('#foo\bar');    // いずれにも一致しない

  console.log('#foo\\bar');              // "#foo\bar"
  console.log('#foo\\\\bar');            // "#foo\\bar"
  document.querySelector('#foo\\bar'); // 最初の div に一致する

  document.querySelector('#foo:bar');    // いずれにも一致しない
  document.querySelector('#foo\\:bar');  // 2番目の div に一致する
</script>

例

あるクラスに一致する最初の要素を探索する

次の例は、クラス "myclass" を持つ文書内の要素の内、最初のものを返します。

var el = document.querySelector(".myclass");

より複雑なセレクター

セレクターは、次の例で示しているように、実に力強いものになり得ます。ここでは、文書内でクラスが "user-panel main" である <div> (<div class="user-panel main">) の中にある、 "login" という名前を持つ最初の <input> 要素 (<input name="login"/>) が返されます。

var el = document.querySelector("div.user-panel.main input[name='login']");

仕様書

ブラウザーの対応

関連情報

• セレクターを使用した DOM 要素の指定
• Element.querySelector()
• Document.querySelectorAll()
• Element.querySelectorAll()
• querySelector のコードスニペット