Document (rozszerzenie)#
document.getElementsByName()#
Metoda getElementsByName() zwraca kolekcję typu NodeList, która zawiera wszystkich potomków typu Element (zgodnie z porządkiem drzewa) znajdujących się w drzewie dokumentu, i mających określoną wartość atrybutu name. W przypadku braku pasujących elementów zwrócona zostanie pusta kolekcja.
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var elements = document.getElementsByName(name);
gdzie poszczególne człony oznaczają:
elements- kolekcja z pasującymi elementami znajdującymi się w drzewie dokumentu.name- łańcuch znakowy reprezentujący wartość atrybutuname, którą zawierają poszukiwane elementy.
Wielkość znaków w wartości atrybutu name oraz w argumencie przekazanym do metody ma znaczenie w dokumentach (X)HTML. Wielkość znaków w nazwie samego atrybutu jest nieistotna tylko w przypadku dokumentów HTML, czyli przykładowo nazwy name lub NAME wskazują na ten sam atrybut.
Metoda ma zastosowanie jedynie w przypadku dokumentów (X)HTML. Zwraca wszystkie elementy z określoną wartością atrybutu name. Dotyczy to także elementów z podanym atrybutem name, które w rzeczywistości nie obsługują go wcale (np. zgodnie ze specyfikacją HTML5). Takie zachowanie występuje w przeglądarkach Firefox, Chrome oraz Opera, ale nie w IE9.
Po kolejnym wywołaniu metody z tym samym argumentem, może zostać zwrócony ten sam obiekt NodeList, który utworzony i zwrócony został we wcześniejszym wywołaniu metody.
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function getCollectionName(){
var newP = document.createElement("p"); // nie został dołączony do drzewa dokumentu dlatego zostanie pominięty
newP.name = "test";
newP.textContent = "Nowy akapit";
var allName = document.getElementsByName("test"); // pobranie kolekcji ze wszystkimi elementami z nazwą "test"
var allNameLen = allName.length;
var info = document.getElementById("info");
var result = "Interfejs kolekcji: " + allName // [object NodeList]
+ "<br>" + "Liczba węzłów: " + allName.length; // 3
for(var i = 0; i < allNameLen; i++){
if (allName[i].textContent != ""){
result += "<br>" + allName[i].textContent;
}
else{
result += "<br>" + allName[i].value;
}
}
info.innerHTML = result;
}
</script>
</head>
<body>
<p name="test">Pierwszy akapit (name="test").</p>
<p name="test">Drugi akapit (name="test").</p>
<p name="Test">Trzeci akapit (name="Test").</p>
<p id="test">Czwarty akapit (id="test").</p>
<input name="test" type="button" value="Pierwszy przycisk (name='test')">
<input name="Test" type="button" value="Drugi przycisk (name='Test')">
<input id="test" type="button" value="Trzeci przycisk (id='test')">
<p>Kliknij przycisk <input type="button" value="getElementsByName('test')" onclick="getCollectionName()"> by pobrać wszystkie elementy o określonej nazwie w dokumencie.</p>
<p style="color: blue;">Szczegółowe informacje dla pobranej kolekcji:</p>
<p id="info"></p>
</body>
</html>Metoda getElementsByName() jest obsługiwana spójnie przez wszystkie wiodące przeglądarki, takie jak Firefox, Chrome czy Opera. Oczywiście nie mogło obyć się bez różnic w produkcie Microsoftu. W przypadku IE9 metoda traktuje atrybuty id oraz name identycznie, nie rozróżnia przy tym wielkości znaków w wartościach tych atrybutów, zwraca kolekcje typu HTMLCollection, w końcu pomija wszystkie elementy, w których podanie atrybutu name nie zostało zdefiniowane w HTML5.
Interfejs Web IDL#
NodeList getElementsByName(DOMString elementName);