document.createElement

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Dans un document HTML, la méthode document.createElement() crée un élément HTML du type spécifié par tagName ou un HTMLUnknownElement si tagName n'est pas reconnu.

Syntaxe

js
var element = document.createElement(tagName[, options]);

Paramètres

tagName

Une chaîne de caractères (DOMString) spécifiant le type d'élément à créer. Le nodeName (nom du noeud) de l'élément créé est initialisé avec la valeur de tagName. N'utilisez pas le nom qualifié (comme "html:a") avec cette méthode. Quand elle est appelée sur un document HTML, createElement() convertit tagName en minuscules avant de créer l'élément. Dans Firefox, Opera et Chrome, createElement(null) fonctionne comme createElement("null").

optionsFacultatif

Un objet ElementCreationOptions facultatif contenant une seule propriété nommée is dont la valeur est le nom de balise d'un élément personnalisé précédemment défini avec customElements.define(). Voir Exemple de composant web pour plus de détails.

Valeur de retour

L'objet Element créé.

Exemples

Exemple de base

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

HTML

html
<!doctype html>
<html>
  <head>
    <title>||Working with elements||</title>
  </head>
  <body>
    <div id="div1">The text above has been created dynamically.</div>
  </body>
</html>

JavaScript

js
document.body.onload = addElement;

function addElement() {
  // crée un nouvel élément div
  var newDiv = document.createElement("div");
  // et lui donne un peu de contenu
  var newContent = document.createTextNode("Hi there and greetings!");
  // ajoute le nœud texte au nouveau div créé
  newDiv.appendChild(newContent);

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

Exemple de composant web

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

js
// 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 :

js
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é avec les versions précédentes de la spécification des éléments personnalisés, quelques navigateurs permettent de passer une chaîne de caractères ici, à la place d'un objet, dont la valeur est la balise de nom de l'élément personnalisé.

Spécifications

Specification
DOM Standard
# ref-for-dom-document-createelement①

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi