Document#
Document.createAttribute()#
Metoda createAttribute() tworzy nowy atrybut z określoną nazwą lokalną dla danego dokumentu.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_attr = document.createAttribute(localName);gdzie poszczególne człony oznaczają:
- new_attr - referencja do nowego atrybutu.
- document - dokument będący obiektem kontekstu.
- localName - łańcuch znakowy reprezentujący nazwę lokalną w nowym atrybucie.
Algorytm wywołania metody createAttribute(localName) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Jeśli localName nie pasuje do wzorca
Namez XML, to zrzuć wyjątek"InvalidCharacterError". - Jeśli obiekt kontekstu jest dokumentem HTML, to niech localName zostanie przekonwertowana na małe znaki ASCII.
- Zwróć nowy obiekt typu
Attr, którego nazwą lokalną jest localName.
Zamiana wielkości znaków w argumencie przekazanym do metody createAttribute() dla dokumentów HTML została wprowadzona dopiero w specyfikacji DOM4. Jest ona wynikiem szeregu zabiegów mających na celu wypracowanie wspólnego stanowiska dla wszystkich poleceń atrybutowych, których zachowanie w poszczególnych przeglądarkach internetowych było wyjątkowo niespójne (DOM - Bug 41, Mozilla - Bug 1205364, Mozilla - Bug 1165851).
Tuż po utworzeniu atrybutu nie będzie on skojarzony z żadnym elementem, dlatego właściwość Attr.ownerElement ma wartość null. Atrybut można przypisać do dowolnego elementu za pomocą dedykowanych metod, takich jak Element.setAttributeNode(), Element.setAttributeNodeNS(), NamedNodeMap.setNamedItem() i NamedNodeMap.setNamedItemNS(). Z drugiej jednak strony nikt nie powinien w ten sposób pracować z atrybutami, istnieją wygodniejsze polecenia wywoływane bezpośrednio na jakimś elemencie.
Obiekt zwracany przez metodę createAttribute() implementuje interfejs Attr, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia).
Więcej szczegółów związanych z elementami, ich potencjalnymi atrybutami oraz spoiwem w postaci mapy nazwanych atrybutów umieściłem w zbiorczym dziale "Podstawy - Elementy i atrybuty".
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function createAttr(localName){
function getInfoAttr(desc, whatDoc, whatAttr){
info.innerHTML += desc
+ "<br>" + "Interfejs dokumentu: " + whatDoc
+ "<br>" + "Interfejs atrybutu: " + whatAttr
+ "<br>" + "Argument z metody: " + localName
+ "<br><br>" + "Właściwość namespaceURI: " + whatAttr.namespaceURI
+ "<br>" + "Właściwość prefix: " + whatAttr.prefix
+ "<br>" + "Właściwość localName: " + whatAttr.localName
+ "<br>" + "Właściwość name: " + whatAttr.name
+ "<br>" + "Właściwość value: " + whatAttr.value
+ "<br>" + "Właściwość nodeValue: " + whatAttr.nodeValue
+ "<br>" + "Właściwość textContent: ";
try{
textContentSupport = whatAttr.textContent;
}
catch(e){
textContentSupport += e;
}
info.innerHTML += textContentSupport
+ "<br>" + "Właściwość ownerElement: " + whatAttr.ownerElement
+ "<br>" + "Właściwość specified: " + whatAttr.specified + "<br><br>";
}
var info = document.getElementById("info");
info.innerHTML = "";
var textContentSupport = "IE zrzuca błąd: ";
try{
var newAttr1 = document.createAttribute(localName);
getInfoAttr("Parametry dla metody createAttribute() w dokumencie HTML:", document, newAttr1);
var newDocXML = document.implementation.createDocument(null, null, null); // nowy dokument XML
var newAttr2 = newDocXML.createAttribute(localName);
getInfoAttr("Parametry dla metody createAttribute() w dokumencie XML:", newDocXML, newAttr2);
}
catch(e){
info.innerHTML = "Przekazanie do metody createAttribute() argumentu niezgodnego z wymogami XML zrzuca błąd:"
+ "<br>" + e // opis zależny od przeglądarki
+ "<br>" + e.constructor; // function DOMException() { [native code] }
}
}
</script>
</head>
<body>
<p>Kliknij konkretny przycisk by utworzyć nowy atrybut o określonej nazwie lokalnej.</p>
<input type="button" value="createAttribute('Test1')" onclick="createAttr('Test1')">
<input type="button" value="createAttribute('test1')" onclick="createAttr('test1')">
<input type="button" value="createAttribute('A:TEST2')" onclick="createAttr('A:TEST2')">
<input type="button" value="createAttribute('a:test2')" onclick="createAttr('a:test2')">
<input type="button" value="createAttribute('0')" onclick="createAttr('0')">
<p style="color: blue;">Szczegółowe informacje o nowym atrybucie:</p>
<p id="info"></p>
</body>
</html>Na chwilę obecną jedynie przeglądarka Firefox obsługuje metodę createAttribute() zgodnie z najnowszymi wymaganiami specyfikacji DOM4. IE nie udostępnia właściwości Attr.textContent w atrybutach tworzonych za pomocą metody createAttribute(), chociaż w przypadku innych poleceń nie ma takich problemów. Chrome traktuje przekazany argument jak nazwę kwalifikowaną w atrybucie, dlatego w pewnych sytuacjach zmienia jego prefiks przestrzeni nazw z domyślnej wartości null (jak w powyższym przykładzie).
Składnia Web IDL#
interface Document : Node { [NewObject] Element createElement(DOMString localName); };