Cette page a été traduite à partir de l'anglais par la communauté.Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.
CustomElementRegistry.define()
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 janvier 2020.
* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.
La méthodedefine(), rattachée à l'interfaceCustomElementRegistry, permet de définir un nouvel élément personnalisé.
Il existe deux types d'éléments personnalisés qu'on peut créer :
- Les éléments personnalisés autonomes
Il s'agit d'éléments autonomes à part entière. Ils n'héritent en rien des éléments HTML natifs.
- Les éléments personnalisés natifs
Ces éléments héritent des éléments HTML natifs et les étendent.
Syntaxe
define(name, constructor)define(name, constructor, options)Parameters
nameLe nom du nouvel élément personnalisé. On notera que le nom d'un élément personnalisé doit contenir un tiret.
constructorLe constructeur du nouvel élément personnalisé.
optionsFacultatifUn objet contrôlant la façon dont l'élément est défini. Il a les propriétés suivantes :
extendsUne chaîne de caractères indiquant le nom de l'élément HTML natif à étendre. On l'utilisera pour créer unélément personnalisé natif.
Valeur de retour
Aucune (undefined.
Exceptions
NotSupportedErrorDOMExceptionException levée :
- Si l'objet
CustomElementRegistrycontient déjà une entrée avec le même nom ou le même constructeur (plus généralement si une telle entrée est déjà définie) - Ou si
extendsest fournie et estun nom valide d'un élément personnalisé - Ou si
extendsest fournie mais que l'élément indiqué est inconnu.
- Si l'objet
SyntaxErrorDOMExceptionException levée si le nom fourni n'est pasun nom valide pour un élément personnalisé.
TypeErrorException levée si le deuxième argument passé n'est pas un constructeur.
Note :Si vous rencontrez l'exceptionNotSupportedError lors d'un appel àdefine(), cela ne signifie pas nécessairement que c'est cette méthode qui échoue. Il s'agit plutôt généralement d'un problème lié àElement.attachShadow().
Exemples
Élément personnalisé autonome
Le code suivant est tiré de notre exemplepopup-info-box-web-component (vous pouvezvoir le résultat de l'exemple ici).
JavaScript
// On crée une classe pour l'élémentclass PopUpInfo extends HTMLElement { constructor() { // On appelle super pour commencer dans le constructeur super(); // On crée une racine sombre const shadow = this.attachShadow({ mode: "open" }); // On crée quelques éléments <span> const wrapper = document.createElement("span"); wrapper.setAttribute("class", "wrapper"); const icon = document.createElement("span"); icon.setAttribute("class", "icon"); icon.setAttribute("tabindex", 0); const info = document.createElement("span"); info.setAttribute("class", "info"); // On prend le contenu de l'attribut et on le place // dans le fragment d'informations const text = this.getAttribute("data-text"); info.textContent = text; // On insère l'icône const img = document.createElement("img"); img.src = this.hasAttribute("img") ? this.getAttribute("img") : "img/default.png"; icon.appendChild(img); // On met en forme const style = document.createElement("style"); console.log(style.isConnected); style.textContent = ` .wrapper { position: relative; } .info { font-size: 0.8rem; width: 200px; display: inline-block; border: 1px solid black; padding: 10px; background: white; border-radius: 10px; opacity: 0; transition: 0.6s all; position: absolute; bottom: 20px; left: 10px; z-index: 3; } img { width: 1.2rem; } .icon:hover + .info, .icon:focus + .info { opacity: 1; } `; // On attache les éléments créés au DOM sombre shadow.appendChild(style); console.log(style.isConnected); shadow.appendChild(wrapper); wrapper.appendChild(icon); wrapper.appendChild(info); }}// On définit le nouvel élémentcustomElements.define("popup-info", PopUpInfo);HTML
<popup-info img="img/alt.png" data-text="Le cryptogramme visuel de votre carte permet une meilleure sécurité. Il s'agit d'une séquence de 3 ou 4 chiffres au dos de votre carte."></popup-info>Note :Les constructeurs pour les éléments personnalisés autonomes doivent étendreHTMLElement.
Élément personnalisé natif
Le code qui suit est tiré de l'exempleword-count-web-component (vous pouvezvoir le résultat de l'exemple ici).
JavaScript
// On crée une classe pour l'élémentclass WordCount extends HTMLParagraphElement { constructor() { // On appelle super pour commencer le constructeur super(); // On compte les mots dans l'élément parent const wcParent = this.parentNode; function countWords(node) { const text = node.innerText || node.textContent; return text .trim() .split(/\s+/g) .filter((a) => a.trim().length > 0).length; } const count = `Mots : ${countWords(wcParent)}`; // On crée une racine sombre const shadow = this.attachShadow({ mode: "open" }); // On crée un nœud texte et on y inscrit le nombre de mot const text = document.createElement("span"); text.textContent = count; // On l'ajoute à la racine sombre shadow.appendChild(text); // On met à jour le compteur lorsque le contenu de l'élément // change setInterval(() => { const count = `Mots : ${countWords(wcParent)}`; text.textContent = count; }, 200); }}// On définit le nouvel élémentcustomElements.define("word-count", WordCount, { extends: "p" });HTML
<p is="word-count"></p>Créer un élément empêchant l'attachement à une racine sombre
Si la classe utilisée pour l'élément contient une propriété statique nomméedisabledFeatures et qui contient la chaîne de caractèresshadow, la méthodeElement.attachShadow() renverra une exceptionDOMExceptionde typeNotSupportedError.
class PopUpInfo extends HTMLElement { static get disabledFeatures() { return ["shadow"]; } constructor() { super(); const shadow = this.attachShadow({ mode: "open" }); // Cela entraînera une erreur lors de la définition de // l'élément. }}Spécifications
| Specification |
|---|
| HTML # dom-customelementregistry-define-dev |