Document#
Document.getElementsByTagName()#
Metoda getElementsByTagName() zwraca kolekcję typu HTMLCollection ze wszystkimi potomkami typu Element o określonej nazwie kwalifikowanej, 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:
var elements = document.getElementsByTagName(qualifiedName);gdzie poszczególne człony oznaczają:
- elements - kolekcja elementowa ze wszystkimi elementami o określonej nazwie kwalifikowanej.
- document - dokument będący obiektem kontekstu.
- qualifiedName - łańcuch znakowy reprezentujący nazwę kwalifikowaną, którą zawierają poszukiwane elementy. W przypadku przekazania "
*" wyszukane zostaną wszystkie elementy, niezależnie od posiadanej nazwy kwalifikowanej.
Algorytm wywołania metody getElementsByTagName(qualifiedName) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
Wielkość znaków w nazwie kwalifikowanej przeszukiwanych elementów oraz w argumencie przekazanym do metody ma znaczenie w przypadku dokumentów XML, natomiast dla dokumentów HTML jest najczęściej nieistotna, chociaż może mieć znaczenie w pewnych specyficznych okolicznościach. Przykładowo polecenie document.getElementsByTagName("FOO") wywołane na dokumencie HTML pasuje do elementów <FOO> w przestrzeni nazw innej niż przestrzeń nazw HTML, do elementów <foo> w przestrzeni nazw HTML, ale nie do elementów <FOO> w przestrzeni nazw HTML.
We wszystkich wcześniejszych specyfikacjach DOM metoda getElementsByTagName() zawsze operowała na nazwie kwalifikowanej w elementach. Było to respektowane przez przeglądarki Firefox i IE (do wersji 11), ale nie przez Operę, tych opartych na Webkicie (np. Chrome czy Safari), a nawet późniejszym Edge. W pewnym momencie (tj. 6 września 2010 roku) zmieniono zachowanie metody w nowym DOM4 tak, żeby traktowała przekazany argument jak nazwę lokalną. W Firefoksie dopiero w 2016 roku próbowano nanieść odpowiednie korekty (Mozilla - Bug 492933), ale szybko okazało się, że jest to niekompatybilne z istniejącymi treściami (głównie ze stroną konfiguracyjną drukarek HP) i zmiany cofnięto. Również w bieżącej wersji specyfikacji DOM powrócono do pierwotnych założeń z poprzednich specyfikacjach DOM (DOM - Bug 143).
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function getCollectionTagName(whatTagName){
var newP = document.createElement("p"); // nie został dołączony do drzewa dokumentu dlatego zostanie pominięty
newP.textContent = "Nowy akapit poza drzewem dokumentu.";
var newDiv = document.createElement("div"); // nie został dołączony do drzewa dokumentu dlatego zostanie pominięty
newDiv.textContent = "Nowy kontener poza drzewem dokumentu.";
var body = document.getElementsByTagName("body")[0]; // referencja do elementu BODY
if (body.firstChild.prefix == null){
var newP2 = document.createElementNS("ns", "test:p");
newP2.textContent = "Nowy akapit 'test:p' bez przestrzeni nazw utworzony i dodany z poziomu skryptu.";
body.insertBefore(newP2, body.firstChild);
var newP3 = document.createElementNS("http://www.w3.org/1999/xhtml", "test:p");
newP3.textContent = "Nowy akapit 'test:p' z przestrzenią nazw HTML utworzony i dodany z poziomu skryptu.";
body.insertBefore(newP3, body.firstChild);
}
var allElement = document.getElementsByTagName(whatTagName); // pobranie kolekcji ze wszystkimi elementami
var allElementLen = allElement.length;
var info = document.getElementById("info");
var result = "Interfejs kolekcji: " + allElement // [object HTMLCollection], Opera i Chrome [object NodeList]
+ "<br>" + "Liczba węzłów: " + allElement.length;
for(var i = 0; i < allElementLen; i++){
var el = allElement[i];
result += "<br><br>" + "Pobrany akapit: " + el.textContent
+ "<br>" + "Właściwość prefix: " + el.prefix
+ "<br>" + "Właściwość localName: " + el.localName
+ "<br>" + "Właściwość nodeName: " + el.nodeName
+ "<br>" + "Właściwość tagName: " + el.tagName
+ "<br>" + "Właściwość namespaceURI: " + el.namespaceURI;
}
info.innerHTML = result;
}
</script>
</head>
<body>
<p>Pierwszy akapit.</p>
<P>Drugi akapit.</p>
<P>Trzeci akapit.</P>
<p>Kliknij przycisk <input type="button" value="getElementsByTagName('p')" onclick="getCollectionTagName('p')"> by pobrać wszystkie akapity p w dokumencie (Czwarty akapit).</p>
<p>Kliknij przycisk <input type="button" value="getElementsByTagName('P')" onclick="getCollectionTagName('P')"> by pobrać wszystkie akapity P w dokumencie (Piąty akapit).</p>
<p>Kliknij przycisk <input type="button" value="getElementsByTagName('test:p')" onclick="getCollectionTagName('test:p')"> by pobrać wszystkie akapity test:p w dokumencie (Szósty akapit).</p>
<p>Kliknij przycisk <input type="button" value="getElementsByTagName('TEST:P')" onclick="getCollectionTagName('TEST:P')"> by pobrać wszystkie akapity TEST:P w dokumencie (Siódmy akapit).</p>
<p>Kliknij przycisk <input type="button" value="getElementsByTagName('div')" onclick="getCollectionTagName('div')"> by pobrać wszystkie kontenery w dokumencie (Ósmy akapit).</p>
<p style="color: blue;">Szczegółowe informacje dla pobranej kolekcji (Dziewiąty akapit):</p>
<span id="info"></span>
</body>
</html>Metoda getElementsByTagName() 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#
interface Document : Node { HTMLCollection getElementsByTagName(DOMString qualifiedName); };