Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

customElements.define — enregistrer un élément personnalisé

customElements.define associe un nom d’élément à un constructeur dans le registre du document. Découvrez la différence entre les éléments personnalisés autonomes et les éléments intégrés personnalisés, ainsi que les principales contraintes d’enregistrement.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });

customElements.define(name, constructor, options) enregistre une définition dans le registre accessible via window.customElements et renvoie undefined, et non une instance ou une promesse. Il s’agit d’une API du HTML Living Standard, pas d’une fonctionnalité d’une édition particulière d’ECMAScript. Les éléments personnalisés autonomes sont pris en charge par les moteurs de navigateur modernes ; la présence de Node 24 dans un dépôt ne prouve pas que cette API est disponible.

Un élément autonome utilise une classe qui étend HTMLElement. Un nom simple valide, comme cktis-greeting, commence par une lettre ASCII minuscule, contient un trait d’union et ne contient aucune lettre ASCII majuscule ; certains noms sont également réservés. L’enregistrement permet de créer des instances et de mettre à niveau les éléments correspondants déjà présents dans le document. À lui seul, il n’insère pas de nouvel élément dans le DOM.

La variante { extends: "button" } définit un élément intégré personnalisé : sa classe étend HTMLButtonElement, et une instance se crée avec document.createElement("button", { is: name }), et non avec document.createElement(name). Vérifiez séparément la prise en charge de cette variante dans les navigateurs ciblés.

Un nom invalide provoque SyntaxError, tandis que la réutilisation d’un nom ou d’un constructeur dans le même registre provoque NotSupportedError ; ces deux erreurs sont des exceptions DOMException. Un argument qui n’est pas un constructeur provoque TypeError. L’exemple définit le contenu dans connectedCallback, après l’ajout de l’élément ; n’ajoutez pas d’enfants ni d’attributs dans le constructeur. Rechargez le document avant de relancer le code : supprimer une instance ne supprime pas sa définition.

Exemples

(() => {
  class CktisGreeting extends HTMLElement {
    connectedCallback() {
      this.textContent = "Hello!";
    }
  }

  customElements.define("cktis-greeting", CktisGreeting);
  const element = document.createElement("cktis-greeting");
  document.body.append(element);
  console.log(element.textContent);
  console.log(element instanceof CktisGreeting);
  element.remove();
})();

Résultat

Hello!
true

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources