Dokument: createElement() Methode

Baseline Weitgehend verfügbar *

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Juli 2015 browserübergreifend verfügbar.

* Einige Teile dieser Funktion werden möglicherweise unterschiedlich gut unterstützt.

Die createElement() Methode des Document-Interfaces erstellt ein neues HTMLElement, das den angegebenen localName hat.

Wenn localName nicht erkannt wird, erstellt die Methode ein HTMLUnknownElement.

Ein String, der den Typ des zu erstellenden Elements angibt. Verwenden Sie keine qualifizierten Namen (wie "html:a") mit dieser Methode. Wenn createElement() in einem HTML-Dokument aufgerufen wird, wird der localName vor der Erstellung des Elements in Kleinbuchstaben umgewandelt. In Firefox, Opera und Chrome funktioniert createElement(null) wie createElement("null").

options Optional

Ein Objekt mit den folgenden optionalen Eigenschaften (beachten Sie, dass nur eines von is und customElementRegistry gesetzt sein darf):

is Optional: Ein String, der den Tag-Namen für ein benutzerdefiniertes Element definiert, das zuvor mit customElements.define() definiert wurde. Das neue Element erhält ein is-Attribut, dessen Wert der Tag-Name des benutzerdefinierten Elements ist. Weitere Details finden Sie im Web-Komponenten-Beispiel.
customElementRegistry Optional: Ein CustomElementRegistry, das das Gescopte benutzerdefinierte Element-Register eines benutzerdefinierten Elements festlegt.

Rückgabewert

Das neue Element.

Hinweis: Ein neues HTMLElement wird zurückgegeben, wenn das Dokument ein HTMLDocument ist, was der häufigste Fall ist. Andernfalls wird ein neues Element zurückgegeben.

Ausnahmen

InvalidCharacterError DOMException

Wird ausgelöst, wenn der Wert von localName kein gültiger Element-Name ist. Ein String ist ein gültiger Element-Name, wenn seine Länge mindestens 1 beträgt und:

er mit einem Alphabetzeichen beginnt und keine ASCII-Leerzeichen, NULL, / oder > enthält (jeweils U+0000, U+002F oder U+003E).
er mit : (U+003A), _ (U+005F) oder einem beliebigen Zeichen im Bereich U+0080 bis U+10FFFF (einschließlich) beginnt und die verbleibenden Codepunkte nur diese gleichen Zeichen zusammen mit den ASCII-Alphanumerischen Zeichen, - (U+002D) und . (U+002E) enthalten.

Hinweis: Frühere Versionen der Spezifikation waren restriktiver und erforderten, dass der localName ein gültiger XML name ist.

NotSupportedError DOMException

Wird ausgelöst, wenn sowohl die Optionen is als auch customElementRegistry angegeben sind.

Beispiele

Einfaches Beispiel

Dies erstellt ein neues <div> und fügt es vor dem Element mit der ID div1 ein.

HTML

html

<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8" />
    <title>Working with elements</title>
  </head>
  <body>
    <div id="div1">The text above has been created dynamically.</div>
  </body>
</html>

JavaScript

function addElement() {
  // create a new div element
  const newDiv = document.createElement("div");

  // and give it some content
  const newContent = document.createTextNode("Hi there and greetings!");

  // add the text node to the newly created div
  newDiv.appendChild(newContent);

  // add the newly created element and its content into the DOM
  const currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}

addElement();

Ergebnis

Web-Komponenten-Beispiel

Hinweis: Überprüfen Sie den Abschnitt über die Browser-Kompatibilität für Unterstützung und das is-Attribut für Hinweise zur Implementierungsrealität von benutzerdefinierten eingebauten Elementen.

Das folgende Beispiel stammt aus unserem expanding-list-web-component-Beispiel (siehe es auch live). In diesem Fall erweitert unser benutzerdefiniertes Element das HTMLUListElement, das das <ul>-Element darstellt.

// Create a class for the element
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Always call super first in constructor
    super();

    // constructor definition left out for brevity
    // …
  }
}

// Define the new element
customElements.define("expanding-list", ExpandingList, { extends: "ul" });

Wenn wir eine Instanz dieses Elements programmatisch erstellen wollten, würden wir einen Aufruf in etwa der folgenden Form verwenden:

let expandingList = document.createElement("ul", { is: "expanding-list" });

Dem neuen Element wird ein is-Attribut gegeben, dessen Wert der Tag-Name des benutzerdefinierten Elements ist.

Hinweis: Aus Gründen der Abwärtskompatibilität erlauben einige Browser, hier einen String anstelle eines Objekts zu übergeben, wobei der Wert des Strings der Tag-Name des benutzerdefinierten Elements ist.