Element
の getElementsByClassName()
メソッドは、引数で与えられたクラス名を含むすべての子要素を、ライブな HTMLCollection
で返します。
Document.getElementsByClassName()
メソッドはこのメソッドとほぼ同様に動作しますが、Document
全体に働きます。特定されたドキュメントルート要素の子孫のうち、与えられたクラス名に合う複数の要素を返します。
構文
var elements = element.getElementsByClassName(names);
引数
names
- マッチさせる一つ以上のクラス名を表す
DOMString
で、クラス名は空白区切りで指定できます。
戻り値
names
で指定したすべてのクラスを持つすべての要素のリストである live な HTMLCollection
です。
使用上の注意
この関数が返すコレクションは常に live です。つまり、この関数を呼び出された要素をルートとする DOM ツリーの現在の状態が常に反映されています。サブツリー上で names
にマッチする新しい要素が追加されたり、サブツリー上にある 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
がすぐに変更されてしまうからです。
var matches = element.getElementsByClassName('colorbox');
for (var i=0; i<matches.length; i++) {
matches[i].classList.remove('colorbox');
matches.item(i).classList.add('hueframe');
}
別の手段を使いましょう。例えば、
var 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
値として Array.prototype
メソッドに与えることで、任意の HTMLCollection
で Array
メソッドを使うことができます。次の例では test
クラスを持つすべての <div>
要素を見つけられます。
var testElements = document.getElementsByClassName('test');
var testDivs = Array.prototype.filter.call(testElements, function(testElement){
return testElement.nodeName === 'DIV';
});
仕様
仕様 | ステータス | コメント |
---|---|---|
DOM Element.getElementsByClassName() の定義 |
現行の標準 | 初期定義 |
ブラウザーの互換性
BCD tables only load in the browser