Document : méthode createElement()

Baseline Widely available *

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.

Dans un document HTML, la méthode createElement() de l'interface Document crée l'élément HTML défini par localName, ou un HTMLUnknownElement si localName n'est pas reconnu.

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

is: Le nom de balise d'un élément personnalisé précédemment défini via customElements.define(). Voir Exemple de composant web pour plus de détails.

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

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 donnera 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é.