Element: getElementsByClassName() メソッド
Element
の getElementsByClassName()
メソッドは、引数で与えられたクラス名を含むすべての子要素を、生きた HTMLCollection
で返します。
getElementsByClassName()
メソッドはこのメソッドとほぼ同様に動作しますが、 Document
全体に働きます。特定された文書ルート要素の子孫のうち、与えられたクラス名に合う複数の要素を返します。
構文
getElementsByClassName(names)
引数
names
-
文字列で、一致させる一つ以上のクラス名を表し、空白区切りで指定できます。
返値
HTMLCollection
で、names
で指定したすべてのクラスを持つすべての要素のライブで更新されるリストです。
使用上の注意
この関数が返すコレクションは常に生きています。つまり、この関数を呼び出された要素をルートとする DOM ツリーの現在の状態が常に反映されています。サブツリー上で names
に一致する新しい要素が追加された場合は、直ちにこのコレクションに追加されます。同様に、サブツリー上にある names
に一致しなかった要素が一致するよう変更された場合も、すぐにこのコレクションに現れます。
逆もしかりです。 names
に一致しなくなったりツリーから外された要素は、すぐにコレクションから除外されます。
メモ: クラス名は後方互換モードでは大文字・小文字が区別されず、それ以外では区別されます。
例
単一のクラスと一致させる
単一の指定されたクラスを含む要素を探すには、 getElementsByClassName()
を呼び出す際にそのクラス名を指定するだけです。
element.getElementsByClassName("test");
この例は main
の id
を持つ要素の子孫の中で、test
クラスをもつ全要素を見つけます。
document.getElementById("main").getElementsByClassName("test");
複数のクラスと一致させる
red
と test
両方のクラスを含んだ要素を見つけます。
element.getElementsByClassName("red test");
結果を調査する
標準の配列構文や、HTMLCollection
の item()
メソッドを使うことで、返されたコレクションの要素を調査することができます。しかし、次の例はうまく動作しないでしょう。colorbox
クラスを外した際に、matches
がすぐに変更されてしまうからです。
const matches = element.getElementsByClassName("colorbox");
for (let i = 0; i < matches.length; i++) {
matches[i].classList.remove("colorbox");
matches.item(i).classList.add("hueframe");
}
別の手段を使いましょう。例えば、
const matches = element.getElementsByClassName("colorbox");
while (matches.length > 0) {
matches.item(0).classList.add("hueframe");
matches[0].classList.remove("colorbox");
}
このコードは、"colorbox"
クラスを持つ子孫要素を見つけ、item(0)
を呼び出して "hueframe"
クラスを追加し、(配列記法で) "colorbox"
を削除します。その後、(もし残っていれば)別の要素が item(0)
になります。
配列のメソッドで結果を抽出する
Array
のメソッドに this
値として HTMLCollection
を渡すことで、
任意の HTMLCollection
に対して配列のメソッドを呼び出すことができます。ここでは、test
のクラスのある <div>
要素をすべて探します。
const testElements = document.getElementsByClassName("test");
const testDivs = Array.prototype.filter.call(
testElements,
(testElement) => testElement.nodeName === "DIV",
);
仕様書
Specification |
---|
DOM Standard # ref-for-dom-element-getelementsbyclassname |
ブラウザーの互換性
BCD tables only load in the browser