Document: getElementsByTagName() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015年7月.

getElementsByTagName はDocument インターフェイスのメソッドで、指定されたタグ名を持つ要素のHTMLCollection を返します。

ルートノードを含めた文書全体が検索されます。返されたHTMLCollection は生きたものであり、つまりdocument.getElementsByTagName() を再度呼び出さなくても DOM ツリーと同期を取り続けるよう、自動的に自分自身を更新します。

構文

getElementsByTagName(name)

引数

name: 要素の名前を表す文字列。特別な文字列* はすべての要素を表します。

返値

生きたHTMLCollection であり、見つかった要素がツリーに出現する順に並んでいます。

メモ:最新の W3C 仕様書では返値はHTMLCollection です。しかし、 WebKit ブラウザーではこのメソッドはNodeList を返します。詳しくはFirefox バグ 14869 を見てください。

以下の例では、getElementsByTagName() は特定の親要素から開始し、その親要素から DOM を上から下へ再帰的に検索し、タグがname 引数と一致する子要素を探します。これはdocument.getElementsByTagName()、および機能的に同等なElement.getElementsByTagName() は、 DOM ツリー内の特定の要素から検索を始めることを示します。

ボタンをクリックするとgetElementsByTagName() を使用して、特定の親 (文書自体または 2 つの<div> 要素の何れかに囲まれたもの) の子孫の段落要素を数えます。

html

<!DOCTYPE html><html lang="ja">  <head>    <meta charset="UTF-8" />    <title>getElementsByTagName の例</title>    <script>      function getAllParaElems() {        const allParas = document.getElementsByTagName("p");        const num = allParas.length;        alert(`この文書には ${num} 個の段落があります`);      }      function div1ParaElems() {        const div1 = document.getElementById("div1");        const div1Paras = div1.getElementsByTagName("p");        const num = div1Paras.length;        alert(`#div1 には ${num} 個の段落があります`);      }      function div2ParaElems() {        const div2 = document.getElementById("div2");        const div2Paras = div2.getElementsByTagName("p");        const num = div2Paras.length;        alert(`#div2 には${num} 個の段落があります`);      }    </script>  </head>  <body>    <p>外部のテキスト</p>    <p>外部のテキスト</p>    <div>      <p>div1 のテキスト</p>      <p>div1 のテキスト</p>      <p>div1 のテキスト</p>      <div>        <p>div2 のテキスト</p>        <p>div2 のテキスト</p>      </div>    </div>    <p>外部のテキスト</p>    <p>外部のテキスト</p>    <button>      文書内のすべての p 要素を表示    </button>    <br />    <button>      div1 要素内のすべての p 要素を表示    </button>    <br />    <button>      div2 要素内のすべての p 要素を表示    </button>  </body></html>

メモ

HTML 文書上で呼び出された場合、getElementsByTagName() は処理前に引数を小文字に変換します。これは HTML 文書内のサブツリーにあるキャメルケースの SVG 要素に一致させようとする場合には望ましくありません。この場合はdocument.getElementsByTagNameNS() が便利です。Firefox バグ 499656 を参照してください。

document.getElementsByTagName() は、検索が文書全体を含むという点以外はElement.getElementsByTagName() と類似しています。