Element.getElementsByClassName()

Esta tradução está incompleta. Ajude a traduzir este artigo em inglês

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

names
Uma DOMString contendo um ou mais nomes de classes separados por espaço em branco.

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.

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';
});

Specifications

Specification Status Comment
DOM
The definition of 'Element.getElementsByClassName()' in that specification.
Padrão em tempo real Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
getElementsByClassNameChrome Full support 1Edge Full support 16
Full support 16
No support 12 — 16
Notes
Notes This function is implemented in the HTMLElement API, meaning non-HTML elements (like SVG elements) cannot use this function.
Firefox Full support 3
Notes
Full support 3
Notes
Notes Prior to Firefox 19, this method was returning a NodeList; it was then changed to reflect the change in the spec.
IE Full support 9
Notes
Full support 9
Notes
Notes This function is implemented in the HTMLElement API, meaning non-HTML elements (like SVG elements) cannot use this function.
Opera Full support 9.5Safari Full support 6WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 6Samsung Internet Android Full support 1.0

Legend

Full support  
Full support
See implementation notes.
See implementation notes.