Utilisation d'lments personnaliss

Vue d'ensemble

Le contrleur des lments personnaliss d'un document Web est l'objet CustomElementRegistry ; cet objet vous permet d'enregistrer un lment personnalis sur une page, de renvoyer des informations sur les lments personnaliss enregistrs, etc..

Pour enregistrer un lment personnalis sur la page, vous utilisez la mthode CustomElementRegistry.define(). Elle prend comme arguments :

• une String reprsentant le nom que vous donnez l'lment ; notez que les noms d'lments personnaliss doivent comprendre un tiret ; ils ne peuvent pas tre des mots simples ;
• un objet de classe dfinissant le comportement de l'lment ;
• facultativement, un objet d'options contenant une proprit extends, qui indique l'lment intgr dont votre lment hrite, le cas chant.

Ainsi, par exemple, la dfinition de notre lment word-count personnalis ressemble ce qui suit :

customElements.define("word-count", WordCount, { extends: "p" });

L'lment est appel word-count, son objet de classe est WordCount, et il tend l'lment <p>.

L'objet de classe d'un lment personnalis est crit en utilisant la syntaxe de classe ES 2015 standard. Par exemple, WordCount est structur comme suit :

class WordCount extends HTMLParagraphElement {
  constructor() {
    // Toujours appeler "super" d'abord dans le constructeur
    super();

    // Ecrire la fonctionnalit de l'lment ici

    ...
  }
}

C'est juste un exemple simple, mais vous pouvez faire plus ici. Il est possible de dfinir des rappels de cycle de vie particuliers dans le constructeur, rappels qui s'excutent des points particuliers du cycle de vie de l'lment. Par exemple, connectedCallback est appel lorsque l'lment personnalis est connect pour la premire fois au DOM du document, tandis que attributeChangedCallback est appel lorsque l'un des attributs de l'lment personnalis est ajout, supprim ou modifi.

Vous en apprendrez plus ce sujet dans notre section Utilisation des rappels de cycle de vie ci-dessous.

Il existe deux types d'lments personnaliss :

• les lments personnaliss autonomes sont indpendants : ils n'hritent pas des lments HTML standard ; vous les utilisez sur une page en les crivant littralement en tant qu'lment HTML ; par exemple <popup-info>, ou document.createElement("popup-info") ;
• les lments intgrs personnaliss hritent des lments HTML de base. Pour en crer un, vous devez spcifier quel lment ils tendent (comme indiqu dans les exemples ci-dessus), et ils sont utiliss en crivant l'lment de base, mais en indiquant le nom de l'lment personnalis dans l'attribut (ou la proprit) is ; par exemple <p is="word-count"> ou document.createElement("p", {is: "word-count"}).

Passage en revue de quelques exemples simples

ce stade, examinons quelques exemples plus simples pour vous montrer plus en dtail comment des lments personnaliss sont crs.

lments personnaliss indpendants

Jetons un coup d'oeil un lment personnalis indpendant : <popup-info-box> (voir un exemple en direct). Il prend une icne d'image et une chane de texte, et intgre l'icne dans la page.

Lorsque l'icne reoit la focalisation, elle affiche le texte dans une bote d'information contextuelle pour fournir d'autres informations contextuelles.

Pour commencer, dans notre fichier JavaScript, nous dfinissons une classe appele PopUpInfo qui tend HTMLElement. Les lments personnaliss indpendants tendent presque toujours HTMLElement.

class PopUpInfo extends HTMLElement {
  constructor() {
    // Toujours appeler "super" d'abord dans le constructeur
    super();

    // Ecrire la fonctionnalit de l'lment ici
    ...
  }
}

On y trouve la dfinition constructor de la classe, qui commence comme toujours par appeler super(), afin que la chane de prototype correcte soit dfinie.

Dans le constructeur, nous dfinissons toutes les fonctionnalits que l'lment aura lorsqu'une instance de celui-ci sera instancie. Dans ce cas, nous attachons une racine fantme l'lment personnalis, nous utilisons une manipulation DOM pour crer la structure DOM interne de l'lment - qui est ensuite attache la racine fantme ; et finalement, nous attachons du CSS la racine fantme pour la mettre en forme.

// Cration d'une racine fantme
var shadow = this.attachShadow({ mode: "open" });

// Cration des spans
var wrapper = document.createElement("span");
wrapper.setAttribute("class", "wrapper");
var icon = document.createElement("span");
icon.setAttribute("class", "icon");
icon.setAttribute("tabindex", 0);
var info = document.createElement("span");
info.setAttribute("class", "info");

// Prendre le contenu de l'attribut et le mettre dans le span d'info
var text = this.getAttribute("text");
info.textContent = text;

// Insrer l'icne
var imgUrl;
if (this.hasAttribute("img")) {
  imgUrl = this.getAttribute("img");
} else {
  imgUrl = "img/default.png";
}
var img = document.createElement("img");
img.src = imgUrl;
icon.appendChild(img);

// Cration du CSS  appliquer au dom fantme
var style = document.createElement("style");

style.textContent =
  ".wrapper {" +
  // CSS tronqu pour la concision

  // Attacher les lments crs au dom fantme

  shadow.appendChild(style);
shadow.appendChild(wrapper);
wrapper.appendChild(icon);
wrapper.appendChild(info);

Enfin, nous enregistrons notre lment personnalis dans le CustomElementRegistry l'aide de la mthode define() mentionne prcdemment ; dans les paramtres, nous spcifions le nom de l'lment, puis le nom de la classe qui dfinit sa fonctionnalit :

customElements.define("popup-info", PopUpInfo);

Il est maintenant disponible pour utilisation dans notre page. Dans notre code HTML, nous l'utilisons comme ceci :

<popup-info
  img="img/alt.png"
  text="Your card validation code (CVC)
  is an extra security feature  it is the last 3 or 4 numbers on the
  back of your card."></popup-info>

Elments intgrs personnaliss

Jetons maintenant un coup d'il un autre exemple d'lment intgr - expanding-list (voir aussi en direct). Cela transforme n'importe quelle liste non ordonne en un menu dployable/refermable.

Tout d'abord, nous dfinissons la classe de notre lment, de la mme manire que prcdemment :

class ExpandingList extends HTMLUListElement {
  constructor() {
    // Toujours appeler "super" d'abord dans le constructeur
    super();

    // Ecrire la fonctionnalit de l'lment ici

    ...
  }
}

Nous n'expliquerons pas en dtail la fonctionnalit de l'lment ici, mais vous pouvez dcouvrir comment elle fonctionne en regardant le code source. La seule vraie diffrence ici est que notre lment tend l'interface HTMLUListElement, et non HTMLElement. Il a donc toutes les caractristiques d'un lment <ul> avec la fonctionnalit que nous dfinissons par dessus, plutt que d'tre un lment indpendant. C'est ce qui en fait un lment intgr personnalis plutt qu'un lment indpendant.

Ensuite, nous enregistrons l'lment en utilisant la mthode define() comme prcdemment, sauf que cette fois, il comprend galement un objet options qui dtaille l'lment dont notre lment personnalis hrite :

customElements.define("expanding-list", ExpandingList, { extends: "ul" });

L'utilisation de l'lment intgr dans un document web se prsente galement de faon quelque peu diffrente :

<ul is="expanding-list">
  ...
</ul>

Vous utilisez l'lment <ul> comme d'habitude, mais vous spcifiez le nom de l'lment personnalis dans l'attribut is.

Utilisation des rappels de cycle de vie

Vous pouvez dfinir plusieurs rappels diffrents dans le constructeur d'un lment personnalis, qui se dclenchent diffrents points du cycle de vie de l'lment :

• connectedCallback : appel lorsque l'lment personnalis est connect pour la premire fois au DOM du document ;
• disconnectedCallback : appel lorsque l'lment personnalis est dconnect du DOM du document ;
• adoptedCallback : appel lorsque l'lment personnalis est dplac vers un nouveau document ;
• attributeChangedCallback : appel lorsque l'un des attributs de l'lment personnalis est ajout, supprim ou modifi.

Jetons un coup d'il un exemple de ceux-ci en cours d'utilisation. Le code ci-dessous est tir de notre exemple de rappels de cycle de vie (le voir s'excuter en direct). C'est un exemple trivial qui gnre simplement un carr color de taille fixe sur la page. L'lment personnalis ressemble ceci :

<custom-square l="100" c="red"></custom-square>

Le constructeur de classe est vraiment simple - ici, nous attachons un DOM l'lment, puis nous attachons les lments vides <div> et <style> la racine fantme :

var shadow = this.attachShadow({ mode: "open" });

var div = document.createElement("div");
var style = document.createElement("style");
shadow.appendChild(style);
shadow.appendChild(div);

La fonction cl dans cet exemple est updateStyle() : elle prend un lment, rcupre sa racine fantme, retrouve son lment <style>, et ajoute width, height, et background-color au style.

function updateStyle(elem) {
  var shadow = elem.shadowRoot;
  var childNodes = shadow.childNodes;
  for (var i = 0; i < childNodes.length; i++) {
    if (childNodes[i].nodeName === "STYLE") {
      childNodes[i].textContent =
        "div {" +
        " width: " +
        elem.getAttribute("l") +
        "px;" +
        " height: " +
        elem.getAttribute("l") +
        "px;" +
        " background-color: " +
        elem.getAttribute("c");
    }
  }
}

Les mises jour relles sont toutes gres par les rappels du cycle de vie, qui sont placs dans le constructeur. Le connectedCallback() s'excute quand l'lment est ajout au DOM : ici, nous excutons la fonction updateStyle() pour nous assurer que le carr est mis en forme comme dfini dans ses attributs :

connectedCallback() {
  console.log('Custom square element added to page.');
  updateStyle(this);
}

Les rappels disconnectedCallback() et adoptedCallback() enregistrent des messages simples sur la console pour nous informer lorsque l'lment est supprim du DOM ou dplac vers une autre page :

disconnectedCallback() {
  console.log('Custom square element removed from page.');
}

adoptedCallback() {
  console.log('Custom square element moved to new page.');
}

Le rappel attributeChangedCallback() est excut chaque fois que l'un des attributs de l'lment est modifi d'une faon ou d'une autre. Comme vous pouvez le voir partir de ses proprits, il est possible d'agir sur les attributs individuellement, en regardant leur nom ainsi que les anciennes et nouvelles valeurs des attributs. Dans ce cas cependant, nous excutons juste la fonction updateStyle() pour nous assurer nouveau que la mise en forme du carr est mise jour selon les nouvelles valeurs :

attributeChangedCallback(name, oldValue, newValue) {
  console.log('Custom square element attributes changed.');
  updateStyle(this);
}

Notez que, pour dclencher le rappel attributeChangedCallback() lorsqu'un attribut change, vous devez observer les attributs. Cela est ralis en spcifiant la mthode static get observedAttributes() dans la classe de l'lment personnalis, en incluant l'intrieur une instruction return qui renvoie un tableau contenant les noms des attributs que vous voulez observer :

static get observedAttributes() {return ['w', 'l']; }

Dans notre exemple, cela est mis au tout dbut du constructeur.