Document#

Document.createElement()#

Metoda createElement() tworzy nowy węzeł typu Element (tzw. węzeł elementowy) z określoną nazwa lokalna, 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:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
var new_element = document.createElement(localName);

gdzie poszczególne człony oznaczają:

Algorytm wywołania metody createElement(localName) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

  1. Jeśli localName nie pasuje do wzorca Name z XML, to zrzuć wyjątek "InvalidCharacterError".
  2. Jeśli obiekt kontekstu jest dokumentem HTML, to niech localName zostanie przekonwertowana na małe znaki ASCII.
  3. Niech namespace będzie przestrzenią nazw HTML jeśli typem zawartości w obiekcie kontekstu jest "text/html" lub "application/xhtml+xml", w przeciwnym razie wartością null.
  4. Niech interface będzie interfejsem elementu dla localName i namespace.

  5. Zwróć nowy węzeł typu Element implementujący interface, bez żadnych atrybutów, z przestrzenią nazw wskazywaną przez namespace, z nazwą lokalną wskazywaną przez localName oraz właścicielem będącym obiektem kontekstu.

Metoda createElement() 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.

Nowy węzeł elementowy zwracany przez metodę createElement() 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ę createElement() 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:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
<!DOCTYPE html>
<html>

<head>

	<script>

		function addElement(localName){

			function getInfoElement(desc, whatDoc, whatElement){

				info.innerHTML += desc
					+ "<br>" + "Interfejs dokumentu: " + whatDoc
					+ "<br>" + "Typ zawartości dokumentu: " + whatDoc.contentType
					+ "<br>" + "Interfejs elementu: " + whatElement
					+ "<br>" + "Argument z metody: " + localName
					+ "<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.createElement(localName);
				newElement1.textContent = "Treść nowego elementu " + newElement1.tagName + " utworzonego w dokumencie HTML (typ zawartości 'text/html').";
				getInfoElement("Parametry dla metody createElement() w dokumencie HTML (typ zawartości 'text/html'):", document, newElement1);

				var newDocXML2 = document.implementation.createDocument(null, null, null); // nowy dokument XML
				var newElement2 = newDocXML2.createElement(localName);
				newElement2.textContent = "Treść nowego elementu " + newElement2.tagName + " utworzonego w dokumencie XML (typ zawartości 'application/xml').";
				getInfoElement("Parametry dla metody createElement() 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.createElement(localName);
				newElement3.textContent = "Treść nowego elementu " + newElement3.tagName + " utworzonego w dokumencie XML (typ zawartości 'application/xhtml+xml').";
				getInfoElement("Parametry dla metody createElement() 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.createElement(localName);
				newElement3.textContent = "Treść nowego elementu " + newElement4.tagName + " utworzonego w dokumencie XML (typ zawartości 'image/svg+xml').";
				getInfoElement("Parametry dla metody createElement() w dokumencie XML (typ zawartości 'image/svg+xml'):", newDocXML4, newElement4);

			}
			catch(e){

				info.innerHTML = "Przekazanie do metody createElement() 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="createElement('p')" onclick="addElement('p')">
	<input type="button" value="createElement('div')" onclick="addElement('div')">
	<input type="button" value="createElement('DIV')" onclick="addElement('DIV')">
	<input type="button" value="createElement('a:DIV')" onclick="addElement('a:DIV')">
	<input type="button" value="createElement('B:noname')" onclick="addElement('B:noname')">
	<input type="button" value="createElement('0')" onclick="addElement('0')">
	<input type="button" value="createElement('')" onclick="addElement('')">

	<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>

Działanie metody createElement() zostało nieco przedefiniowane w aktualnej specyfikacji DOM4. Zmiany koncentrują się głównie na sposobie ustawiania wartości w poszczególnych właściwościach dla nowego elementu, takich jak Element.tagName, Node.nodeName, Element.localName, Element.namespaceURI, itd. Wszystkie aktualne przeglądarki internetowe są zgodne z zaleceniami DOM4, dlatego też wytycznych z poprzednich specyfikacji nie ma sensu w ogóle prezentować.

Składnia Web IDL#

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
interface Document : Node {
	[NewObject] Element createElement(DOMString localName);
};

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

Document (H1) Document.createElement() (H2) Opis działania (H3) Składnia Web IDL (H3) Specyfikacje i inne materiały (H3)