Element.getElementsByClassName()
O método getElementsByClassName()
da interface Element
retorna um HTMLCollection
atualizado simultaneamente que contém todos os elementos descendentes da classe ou das classes especificadas.
O método getElementsByClassName()
da interface Document
funciona da mesma forma, exceto que atua em todo o documento, começando da raíz.
Sintaxe
var elements = element.getElementsByClassName(names);
Parâmetros
Valor de retorno
Um HTMLCollection
que contém uma lista de elementos atualizada em tempo real com todos os elementos que são membros das classes especificadas em names
.
Notas de uso
Habitualmente, o conjunto de elementos retornado será atualizado simultaneamente com as mudanças feitas, refletindo no estado atual da árvore DOM, no elemento em que a função foi chamada. Assim que novos elementos que satisfazem as classes contidas em names
são adicionados na subárvore, eles imediatamente aparecem no conjunto de elementos. Em um exemplo similar, se um elemento existente que não satisfaz nenhuma classe contida em names
tem as suas classes ajustadas para que satisfaça, ele irá instantaneamente ser adicionado ao conjunto de elementos.
O oposto disso também acontece; os elementos que não satisfazerem mais as classes contidas em name
serão removidos instantaneamente do conjunto.
Nota: No modo quirks, o nome das classes são comparadas da forma case-insensitive. Caso contrário, considere case sensitive.
Exemplos
Usando uma única classe
Para procurarmos elementos que incluem uma classe específica, nós apenas informamos o nome da classe ao chamar getElementsByClassName()
:
element.getElementsByClassName("test");
Esse exemplo retorna todos os elementos que possuem a classe test
, e que também são filhos do elemento que possui o id
com valor main
:
document.getElementById("main").getElementsByClassName("test");
Usando várias classes
Para retornar elementos que incluem as classes red
and test
:
element.getElementsByClassName("red test");
Examinando os resultados
You can use either the item()
method on the returned HTMLCollection
or standard array syntax to examine individual elements in the collection. However the following code will not work as one might expect because "matches"
will change as soon as any "colorbox"
class is removed.
var matches = element.getElementsByClassName("colorbox");
for (var i = 0; i < matches.length; i++) {
matches[i].classList.remove("colorbox");
matches.item(i).classList.add("hueframe");
}
Instead, use another method, such as:
var matches = element.getElementsByClassName("colorbox");
while (matches.length > 0) {
matches.item(0).classList.add("hueframe");
matches[0].classList.remove("colorbox");
}
This code finds descendant elements with the "colorbox"
class, adds the class "hueframe"
, by calling item(0)
, then removes "colorbox"
(using array notation). Another element (if any are left) will then become item(0)
.
Filtering the results using array methods
We can also use methods of Array.prototype
on any HTMLCollection
by passing the HTMLCollection
as the method's this
value. Here we'll find all <div>
elements that have a class of test
:
var testElements = document.getElementsByClassName("test");
var testDivs = Array.prototype.filter.call(
testElements,
function (testElement) {
return testElement.nodeName === "DIV";
},
);
Especificações
Specification |
---|
DOM Standard # ref-for-dom-element-getelementsbyclassname |
Compatibilidade com navegadores
BCD tables only load in the browser