Document : méthode createElement()

Baseline Large disponibilité *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

En savoir plus
Voir la compatibilité complète

La méthode createElement() de l'interface Document crée un nouvel HTMLElement ayant le localName défini.

Si le localName n'est pas reconnu, la méthode crée un HTMLUnknownElement.

Une chaîne de caractères définissant le type d'élément à créer. N'utilisez pas de noms qualifiés (comme « html:a ») avec cette méthode. Lorsqu'elle est appelée sur un document HTML, createElement() convertit localName en minuscules avant de créer l'élément. Dans Firefox, Opera et Chrome, createElement(null) fonctionne comme createElement("null").

options Facultatif

Un objet avec les propriétés optionnelles suivantes (notez que seule l'une des propriétés is et customElementRegistry peut être définie) :

is Facultatif: Une chaîne de caractères définissant le nom de balise d'un élément personnalisé précédemment défini avec customElements.define(). Le nouvel élément reçoit un attribut is dont la valeur est le nom de balise de l'élément personnalisé. Voir Exemple de composant web pour plus de détails.
customElementRegistry Facultatif: Un objet CustomElementRegistry qui définit le registre d'éléments personnalisés à portée locale d'un élément personnalisé.

Valeur de retour

L'objet Element créé.

Note : Un nouvel élément HTML est retourné si le document est un document HTML, ce qui est le cas le plus courant. Sinon, un nouvel élément est retourné.

Exceptions

InvalidCharacterError DOMException

Levée si la valeur de localName n'est pas un nom d'élément valide. Une chaîne de caractères est un nom d'élément valide si sa longueur est d'au moins 1 et :

elle commence par un caractère alphabétique et ne contient pas d'espaces ASCII, NULL, / ou > (U+0000, U+002F ou U+003E, respectivement).
elle commence par : (U+003A), _ (U+005F), ou tout caractère dans la plage U+0080 à U+10FFFF (inclus), et les points de code restants ne contiennent que ces mêmes caractères ainsi que les caractères alphanumériques ASCII, - (U+002D) et . (U+002E),

Note : Les versions antérieures de la spécification étaient plus restrictives, exigeant que le localName soit un nom XML ^(angl.) valide.

NotSupportedError DOMException

Levée si les options is et customElementRegistry sont toutes deux définies.

Exemples

Exemple simple

Ici est créé un nouveau <div> qui est inséré avant l'élément avec l'identifiant "div1".

HTML

html

<!doctype html>
<html lang="fr">
  <head>
    <title>||Travailler avec les éléments||</title>
  </head>
  <body>
    <div id="div1">Le texte ci-dessus a été créé dynamiquement.</div>
  </body>
</html>

JavaScript

document.body.onload = addElement;

function addElement() {
  // crée un nouvel élément div
  const newDiv = document.createElement("div");

  // et lui donne un peu de contenu
  const newContent = document.createTextNode("Bonjour et salutations !");

  // ajoute le nœud texte au nouveau div créé
  newDiv.appendChild(newContent);

  // ajoute le nouvel élément créé et son contenu dans le DOM
  const currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}

Résultat

Exemple de composant web

Note : Vérifiez la section compatibilité des navigateurs pour le support, et la référence de l'attribut is pour les mises en garde sur la réalité de l'implémentation des éléments intégrés personnalisés.

L'exemple de fragment suivant est extrait de notre exemple expanding-list-web-component ^(angl.) (voir également en direct ^(angl.)). Dans ce cas, notre élément personnalisé étend la HTMLUListElement, qui représente l'élément HTML <ul>.

// Crée une classe pour l'élément
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Toujours appeler « super » en premier dans le constructeur
    super();

    // définition du constructeur omise pour la brièveté
    ...
  }
}

// Définit le nouvel élément
customElements.define('expanding-list', ExpandingList, { extends: 'ul' });

Si nous cherchons à créer une instance de cet élément par programmation, nous devons utiliser un appel tel que montré dans la ligne suivante :

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

Le nouvel élément donne un attribut is dont la valeur est la balise de nom de l'élément personnalisé.

Note : Pour la rétrocompatibilité, certains navigateurs permettent de passer une chaîne de caractères ici à la place d'un objet, où la valeur de la chaîne de caractères est le nom de la balise de l'élément personnalisé.