Document#

Document.getElementsByClassName()#

Metoda getElementsByClassName() zwraca kolekcję typu HTMLCollection ze wszystkimi potomkami typu Element o określonych klasach, którzy znajdują się w danym dokumencie (zgodnie z porządkiem drzewa). W przypadku braku pasujących elementów zwrócona zostanie pusta kolekcja.

Opis działania#

Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
var elements = document.getElementsByClassName(classNames);

gdzie poszczególne człony oznaczają:

Algorytm wywołania metody getElementsByClassName(classNames) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

  1. Zwróć listę elementów z nazwami klas classNames dla obiektu kontekstu.

Wielkość znaków w nazwach klas przeszukiwanych elementów oraz w argumencie przekazanym do metody ma znaczenie, dotyczy to zarówno dokumentu XML jak i dokumentu HTML (ale tylko w trybie bez dziwactw dla tego drugiego). Zatem dla dokumentu HTML w starszych trybach renderowania polecenie document.getElementByClassName("test") zwróci kolekcję elementową dopasowującą element reprezentowany przez zapis znacznikowy <div class="Test"></div>.

Niezależnie od zawiłych regułek działanie metody getElementsByClassName() najlepiej wyjaśnić na suchym przykładzie:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
<div>
	<p id="p1" class="aaa bbb"></p>
	<p id="p2" class="aaa ccc"></p>
	<p id="p3" class="bbb ccc"></p>
</div>

W powyższej strukturze znacznikowej efektem następujących wywoływań na obiekcie dokumentu będzie:

Należy zauważyć, że dopasowanie następuje jedynie wtedy, kiedy wszystkie klasy w argumencie przekazanym do metody znajdują się w atrybucie class przeszukiwanego elementu, przy czym kolejność występowania klas zarówno w argumencie metody, jak i w wartości atrybutu jest nieistotna.

Prosty przykład:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
<!DOCTYPE html>
<html>

<head>

	<script>

		function getCollectionClass(className){

			var newP = document.createElement("p"); // nie został dołączony do drzewa dokumentu dlatego zostanie pominięty
			newP.className = "test1";
			newP.textContent = "Nowy akapit";

			var allClass = document.getElementsByClassName(className); // pobranie kolekcji ze wszystkimi elementami o określonej klasie
			var allClassLen = allClass.length;

			var info = document.getElementById("info");

			var result = "Interfejs kolekcji: " + allClass // [object HTMLCollection], Opera i Chrome [object NodeList]
					+ "<br>" + "Liczba węzłów: " + allClass.length;

			for(var i = 0; i < allClassLen; i++){

				result += "<br>" + allClass[i].textContent;

			}

			info.innerHTML = result;

		}

	</script>

</head>

<body>
	<p class="test1">Pierwszy akapit (class="test1").</p>
	<p class="test1 test2">Drugi akapit (class="test1 test2").</p>
	<p class="test1 test2 test3">Trzeci akapit (class="test1 test2 test3").</p>
	<p class="Test1">Czwarty akapit (class="Test1").</p>

	<p>Kliknij konkretny przycisk by pobrać wszystkie elementy o określonych klasach w dokumencie.</p>
	<input type="button" value="getElementsByClassName('test1')" onclick="getCollectionClass('test1')">
	<input type="button" value="getElementsByClassName('test1 test2')" onclick="getCollectionClass('test1 test2')">
	<input type="button" value="getElementsByClassName('test3 test1')" onclick="getCollectionClass('test3 test1')">
	<input type="button" value="getElementsByClassName('test3 test4')" onclick="getCollectionClass('test3 test4')">
	<input type="button" value="getElementsByClassName('')" onclick="getCollectionClass('')">

	<p style="color: blue;">Szczegółowe informacje dla pobranej kolekcji:</p>
	<p id="info"></p>
</body>

</html>

Zysk wydajnościowy ze stosowania metody getElementsByClassName() (w porównaniu z innymi alternatywnymi rozwiązaniami) zaprezentował John Resig w artykule "getElementsByClassName Speed Comparison".

Metoda getElementsByClassName() pojawia się dopiero w specyfikacji DOM4. Została zdefiniowana także w interfejsie Element, dlatego może być bezproblemowo wywoływana na węzłach typu Element.

Składnia Web IDL#

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
interface Document : Node {
	HTMLCollection getElementsByClassName(DOMString classNames);
};

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

Document (H1) Document.getElementsByClassName() (H2) Opis działania (H3) Składnia Web IDL (H3) Specyfikacje i inne materiały (H3)