Document#
Document.createElementNS()#
Metoda createElementNS() tworzy nowy węzeł typu Element (tzw. węzeł elementowy) z określoną przestrzenią nazw i nazwą kwalifikowana, którego właścicielem jest dany dokument.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_element = document.createElementNS(namespace, qualifiedName);gdzie poszczególne człony oznaczają:
- new_element - referencja do nowego węzła elementowego.
- document - dokument będący obiektem kontekstu.
- namespace - łańcuch znakowy reprezentujący przestrzeń nazw w nowym węźle elementowym lub wartość
null. Pusty łańcuch znakowy ma identyczne działanie jak przekazanie wartościnull. - qualifiedName - łańcuch znakowy reprezentujący nazwę kwalifikowaną w nowym węźle elementowym.
Algorytm wywołania metody createElementNS(namespace, qualifiedName) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Niech namespace, prefix oraz localName będą wynikiem przekazania namespace i qualifiedName do weryfikacji i wydobycia. Zrzuć ponownie każdy wyjątek.
- Niech interface będzie interfejsem elementu dla localName i namespace.
- Zwróć nowy węzeł typu
Elementimplementujący interface, bez żadnych atrybutów, z przestrzenią nazw wskazywaną przez namespace, z prefiksem przestrzeni nazw wskazywanym przez prefix, z nazwą lokalną wskazywaną przez localName oraz właścicielem będącym obiektem kontekstu.
Analizując dokładnie wszystkie powiązane z metodą createElementNS() algorytmy można zauważyć, że istnieje wiele kombinacji dla argumentów przekazywanych do metody, które najczęściej powodują zrzucenie wyjątku "NamespaceError", co jest konsekwencją niewłaściwego stosowania przestrzeni nazw.
Metoda createElementNS() to jedna z najważniejszych metod konstruujących w całym DOM. Pozwala na bezpośrednie tworzenie nowych elementów dla dowolnego dokumentu lub każdego innego drzewa węzłów. Jej stosowanie 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 nazw HTML najczęściej wystarczy standardowa metoda Document.createElement().
Nowy węzeł elementowy zwracany przez metodę createElementNS() nie jest częścią danego drzewa dokumentu dopóki nie zostanie dodany do innego węzła należącego do drzewa dokumentu. Dlatego nowy węzeł elementowy nie będzie posiadał rodzica (wartość null), aczkolwiek dalej posiada jakiegoś właściciela.
Obiekt zwracany przez metodę createElementNS() implementuje interfejs Element (lub inny bardziej wyspecjalizowany interfejs dziedziczący po nim), 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 addElement(namespace, qualifiedName){
function getInfoElement(desc, whatDoc, whatElement){
info.innerHTML += desc
+ "<br>" + "Interfejs dokumentu: " + whatDoc
+ "<br>" + "Typ zawartości dokumentu: " + whatDoc.contentType
+ "<br>" + "Interfejs elementu: " + whatElement
+ "<br>" + "Pierwszy argument z metody: " + namespace
+ "<br>" + "Drugi argument z metody: " + qualifiedName
+ "<br><br>" + "Właściwość localName: " + whatElement.localName
+ "<br>" + "Właściwość nodeName: " + whatElement.nodeName
+ "<br>" + "Właściwość tagName: " + whatElement.tagName
+ "<br>" + "Właściwość prefix: " + whatElement.prefix
+ "<br>" + "Właściwość namespaceURI : " + whatElement.namespaceURI
+ "<br>" + "Właściwość ownerDocument: " + whatElement.ownerDocument + "<br><br>";
document.body.appendChild(whatElement);
}
var info = document.getElementById("info");
info.innerHTML = "";
try{
var newElement1 = document.createElementNS(namespace, qualifiedName);
newElement1.textContent = "Treść nowego elementu " + newElement1.tagName + " utworzonego w dokumencie HTML (typ zawartości 'text/html').";
getInfoElement("Parametry dla metody createElementNS() w dokumencie HTML (typ zawartości 'text/html'):", document, newElement1);
var newDocXML2 = document.implementation.createDocument(null, null, null); // nowy dokument XML
var newElement2 = newDocXML2.createElementNS(namespace, qualifiedName);
newElement2.textContent = "Treść nowego elementu " + newElement2.tagName + " utworzonego w dokumencie XML (typ zawartości 'application/xml').";
getInfoElement("Parametry dla metody createElementNS() w dokumencie XML (typ zawartości 'application/xml'):", newDocXML2, newElement2);
var newDocXML3 = document.implementation.createDocument("http://www.w3.org/1999/xhtml", null, null); // nowy dokument XML
var newElement3 = newDocXML3.createElementNS(namespace, qualifiedName);
newElement3.textContent = "Treść nowego elementu " + newElement3.tagName + " utworzonego w dokumencie XML (typ zawartości 'application/xhtml+xml').";
getInfoElement("Parametry dla metody createElementNS() w dokumencie XML (typ zawartości 'application/xhtml+xml'):", newDocXML3, newElement3);
var newDocXML4 = document.implementation.createDocument("http://www.w3.org/2000/svg", null, null); // nowy dokument XML
var newElement4 = newDocXML4.createElementNS(namespace, qualifiedName);
newElement3.textContent = "Treść nowego elementu " + newElement4.tagName + " utworzonego w dokumencie XML (typ zawartości 'image/svg+xml').";
getInfoElement("Parametry dla metody createElementNS() w dokumencie XML (typ zawartości 'image/svg+xml'):", newDocXML4, newElement4);
}
catch(e){
info.innerHTML = "Przekazanie do metody createElementNS() 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ć i dodać nowy element do dokumentu.</p>
<input type="button" value="createElementNS('http://www.w3.org/1999/xhtml', 'p')" onclick="addElement('http://www.w3.org/1999/xhtml', 'p')">
<input type="button" value="createElementNS('http://www.w3.org/1999/xhtml', 'a:p')" onclick="addElement('http://www.w3.org/1999/xhtml', 'a:p')">
<input type="button" value="createElementNS('http://www.w3.org/1999/xhtml', 'DIV')" onclick="addElement('http://www.w3.org/1999/xhtml', 'DIV')">
<input type="button" value="createElementNS('http://www.w3.org/1999/xhtml', 'a:DIV')" onclick="addElement('http://www.w3.org/1999/xhtml', 'a:DIV')">
<input type="button" value="createElementNS('', 'p')" onclick="addElement('', 'p')">
<input type="button" value="createElementNS(null, 'noname')" onclick="addElement(null, 'noname')">
<input type="button" value="createElementNS('', 'noname')" onclick="addElement('', 'noname')">
<input type="button" value="createElementNS('ns1', 'B:NONAME')" onclick="addElement('ns1', 'B:NONAME')">
<input type="button" value="createElementNS('ns1', 'b:noname')" onclick="addElement('ns1', 'b:noname')">
<input type="button" value="createElementNS('', '0')" onclick="addElement('', '0')">
<input type="button" value="createElementNS('', 'B:noname')" onclick="addElement('', 'B:noname')">
<p style="color: blue;">Szczegółowe informacje o nowym elemencie:</p>
<p id="info"></p>
<p style="color: blue;">Nowe elementy dodane do dokumentu:</p>
</body>
</html>Składnia Web IDL#
interface Document : Node { [NewObject] Element createElementNS(DOMString? namespace, DOMString qualifiedName); };