Document#
Document.getElementsByTagNameNS()#
Metoda getElementsByTagNameNS() zwraca kolekcję typu HTMLCollection ze wszystkimi potomkami typu Element o określonej przestrzeni nazw i nazwie lokalnej, 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.getElementsByTagNameNS(namespace, localName);gdzie poszczególne człony oznaczają:
- elements - kolekcja elementowa ze wszystkimi elementami o określonej przestrzeni nazw i nazwie lokalnej.
- document - dokument będący obiektem kontekstu.
- namespace - łańcuch znakowy reprezentujący przestrzeń nazw, do której należą poszukiwane elementy. W przypadku przekazania "
*" wyszukane zostaną wszystkie elementy, niezależnie od posiadanej przestrzeni nazw. Wartośćnullma identyczne działanie jak przekazanie pustego łańcucha znakowego. - localName - łańcuch znakowy reprezentujący nazwę lokalną, którą zawierają poszukiwane elementy. W przypadku przekazania "
*" wyszukane zostaną wszystkie elementy, niezależnie od posiadanej nazwy lokalnej.
Algorytm wywołania metody getElementsByTagNameNS(namespace, localName) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Zwróć listę elementów z przestrzenią nazw namespace i nazwą lokalną localName dla obiektu kontekstu.
Wielkość znaków w przestrzeni nazw i nazwie lokalnej przeszukiwanych elementów oraz w argumentach przekazanych do metody ma znaczenie zarówno w dokumentach XML, jak i w dokumentach HTML.
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function getCollectionTagNameNS(whatNamespce, whatTagName){
var newP = document.createElement("p"); // nie został dołączony do drzewa dokumentu dlatego zostanie pominięty6
newP.textContent = "Nowy akapit";
var newDiv = document.createElement("div"); // nie został dołączony do drzewa dokumentu dlatego zostanie pominięty
newDiv.textContent = "Nowy kontener";
var body = document.getElementsByTagName("body")[0]; // referencja do elementu BODY
if (body.firstChild.tagName != "P"){
var newP2 = document.createElementNS("", "P");
newP2.textContent = "Nowy akapit bez przestrzeni nazw utworzony i dodany z poziomu skryptu.";
body.insertBefore(newP2, body.firstChild);
}
var allElement = document.getElementsByTagNameNS(whatNamespce, 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ść 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="getElementsByTagNameNS('*', 'p')" onclick="getCollectionTagNameNS('*', 'p')"> by pobrać wszystkie akapity p w dokumencie (Czwarty akapit).</p>
<p>Kliknij przycisk <input type="button" value="getElementsByTagNameNS('*', 'P')" onclick="getCollectionTagNameNS('*', 'P')"> by pobrać wszystkie akapity P w dokumencie (Piąty akapit).</p>
<p>Kliknij przycisk <input type="button" value="getElementsByTagNameNS('*', 'div')" onclick="getCollectionTagNameNS('*', 'div')"> by pobrać wszystkie kontenery w dokumencie (Szósty akapit).</p>
<p style="color: blue;">Szczegółowe informacje dla pobranej kolekcji (Siódmy akapit):</p>
<span id="info"></span>
</body>
</html>Metoda getElementsByTagNameNS() została zdefiniowana także w interfejsie Element, dlatego może być bezproblemowo wywoływana na węzłach typu Element. Stosowanie metody będzie miało sens w dokumentach XML, gdzie można wymieszać ze sobą wiele języków XML, czyli mogą pojawić się elementy o tych samych nazwach lokalnych, ale w różnych przestrzeniach nazw. W przypadku dokumentów HTML z elementami w przestrzeni HTML najczęściej wystarczy standardowa metoda Document.getElementsByTagName().
Składnia Web IDL#
interface Document : Node { HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName); };