From 8bdcf31f79fdecafb6d4a5e13fd1fd01c767a823 Mon Sep 17 00:00:00 2001 From: julieng Date: Thu, 11 Nov 2021 08:43:25 +0100 Subject: convert content to md --- .../web_components/using_custom_elements/index.md | 204 +++++++++++---------- 1 file changed, 111 insertions(+), 93 deletions(-) (limited to 'files/fr/web/web_components/using_custom_elements') diff --git a/files/fr/web/web_components/using_custom_elements/index.md b/files/fr/web/web_components/using_custom_elements/index.md index e01061d005..5fe0e7d7d6 100644 --- a/files/fr/web/web_components/using_custom_elements/index.md +++ b/files/fr/web/web_components/using_custom_elements/index.md @@ -10,35 +10,34 @@ tags: - customized translation_of: Web/Web_Components/Using_custom_elements --- -
{{DefaultAPISidebar("Web Components")}}
+{{DefaultAPISidebar("Web Components")}} -

L'un des aspects les plus importants des composants web est la possibilité de créer des éléments personnalisés qui encapsulent bien vos fonctionnalités sur une page HTML, plutôt que de devoir se contenter d'une soupe de balises définissant des fonctionnalités personnalisées. Cet article passe en revue les bases de l'utilisation d'éléments personnalisés.

+L'un des aspects les plus importants des composants web est la possibilité de créer des éléments personnalisés qui encapsulent bien vos fonctionnalités sur une page HTML, plutôt que de devoir se contenter d'une soupe de balises définissant des fonctionnalités personnalisées. Cet article passe en revue les bases de l'utilisation d'éléments personnalisés. -
-

Note : Les éléments personnalisés sont pris en charge par défaut dans Chrome et Opera. Firefox en est très proche, ils sont disponibles si vous mettez les préférences dom.webcomponents.enabled et dom.webcomponents.customelements.enabled à true, leur implémentation étant prévue pour être activée par défaut dans la version 60/61. Safari ne prend en charge que les éléments personnalisés indépendants pour l'instant, et Edge travaille de même sur une implémentation.

-
+> **Note :** Les éléments personnalisés sont pris en charge par défaut dans Chrome et Opera. Firefox en est très proche, ils sont disponibles si vous mettez les préférences dom.webcomponents.enabled et dom.webcomponents.customelements.enabled à true, leur implémentation étant prévue pour être activée par défaut dans la version 60/61. Safari ne prend en charge que les éléments personnalisés indépendants pour l'instant, et Edge travaille de même sur une implémentation. -

Vue d'ensemble

+## Vue d'ensemble -

Le contrôleur des éléments personnalisés d'un document Web est l'objet {{domxref("CustomElementRegistry")}} ; cet objet vous permet d'enregistrer un élément personnalisé sur une page, de renvoyer des informations sur les éléments personnalisés enregistrés, etc..

+Le contrôleur des éléments personnalisés d'un document Web est l'objet {{domxref("CustomElementRegistry")}} ; cet objet vous permet d'enregistrer un élément personnalisé sur une page, de renvoyer des informations sur les éléments personnalisés enregistrés, etc.. -

Pour enregistrer un élément personnalisé sur la page, vous utilisez la méthode {{domxref ("CustomElementRegistry.define()")}}. Elle prend comme arguments :

+Pour enregistrer un élément personnalisé sur la page, vous utilisez la méthode {{domxref ("CustomElementRegistry.define()")}}. Elle prend comme arguments : - +- une {{domxref("DOMString")}} représentant le nom que vous donnez à l'élément ; notez que les noms d'éléments personnalisés doivent comprendre un tiret ; ils ne peuvent pas être des mots simples ; +- un objet de classe définissant le comportement de l'élément ; +- facultativement, un objet d'options contenant une propriété extends, qui indique l'élément intégré dont votre élément hérite, le cas échéant. -

Ainsi, par exemple, la définition de notre élément word-count personnalisé ressemble à ce qui suit :

+Ainsi, par exemple, la définition de notre [élément word-count](https://mdn.github.io/web-components-examples/word-count-web-component/) personnalisé ressemble à ce qui suit : -
customElements.define('word-count', WordCount, { extends: 'p' });
+```js +customElements.define('word-count', WordCount, { extends: 'p' }); +``` -

L'élément est appelé word-count, son objet de classe est WordCount, et il étend l'élément {{htmlelement("p")}}.

+L'élément est appelé `word-count`, son objet de classe est `WordCount`, et il étend l'élément {{htmlelement("p")}}. -

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

+L'objet de classe d'un élément personnalisé est écrit en utilisant la syntaxe de classe ES 2015 standard. Par exemple, `WordCount` est structuré comme suit : -
class WordCount extends HTMLParagraphElement {
+```js
+class WordCount extends HTMLParagraphElement {
   constructor() {
     // Toujours appeler "super" d'abord dans le constructeur
     super();
@@ -47,32 +46,32 @@ translation_of: Web/Web_Components/Using_custom_elements
 
     ...
   }
-}
+} +``` -

C'est juste un exemple simple, mais vous pouvez faire plus ici. Il est possible de définir des rappels de cycle de vie particuliers dans le constructeur, rappels qui s'exécutent à des points particuliers du cycle de vie de l'élément. Par exemple, connectedCallback est appelé lorsque l'élément personnalisé est connecté pour la première fois au DOM du document, tandis que attributeChangedCallback est appelé lorsque l'un des attributs de l'élément personnalisé est ajouté, supprimé ou modifié.

+C'est juste un exemple simple, mais vous pouvez faire plus ici. Il est possible de définir des rappels de cycle de vie particuliers dans le constructeur, rappels qui s'exécutent à des points particuliers du cycle de vie de l'élément. Par exemple, `connectedCallback` est appelé lorsque l'élément personnalisé est connecté pour la première fois au DOM du document, tandis que `attributeChangedCallback` est appelé lorsque l'un des attributs de l'élément personnalisé est ajouté, supprimé ou modifié. -

Vous en apprendrez plus à ce sujet dans notre section {{anch("Using the lifecycle callbacks")}} ci-dessous.

+Vous en apprendrez plus à ce sujet dans notre section {{anch("Using the lifecycle callbacks")}} ci-dessous. -

Il existe deux types d'éléments personnalisés :

+Il existe deux types d'éléments personnalisés : - +- les **éléments personnalisés autonomes** sont indépendants : ils n'héritent pas des éléments HTML standard ; vous les utilisez sur une page en les écrivant littéralement en tant qu'élément HTML ; par exemple ``, ou `document.createElement("popup-info")` ; +- les `éléments intégrés personnalisés` héritent des éléments HTML de base. Pour en créer un, vous devez spécifier quel élément ils étendent (comme indiqué dans les exemples ci-dessus), et ils sont utilisés en écrivant l'élément de base, mais en indiquant le nom de l'élément personnalisé dans l'attribut (ou la propriété) {{htmlattrxref("is" )}} ; par exemple \

ou document.createElement("p", {is: "word-count"}). -

Passage en revue de quelques exemples simples

+## Passage en revue de quelques exemples simples -

À ce stade, examinons quelques exemples plus simples pour vous montrer plus en détail comment des éléments personnalisés sont créés.

+À ce stade, examinons quelques exemples plus simples pour vous montrer plus en détail comment des éléments personnalisés sont créés. -

Éléments personnalisés indépendants

+### Éléments personnalisés indépendants -

Jetons un coup d'oeil à un élément personnalisé indépendant : <popup-info-box> (voir un exemple en direct). Il prend une icône d'image et une chaîne de texte, et intègre l'icône dans la page.

+Jetons un coup d'oeil à un élément personnalisé indépendant : [\](https://github.com/mdn/web-components-examples/tree/master/popup-info-box-web-component) (voir un [exemple en direct](https://mdn.github.io/web-components-examples/popup-info-box-web-component/)). Il prend une icône d'image et une chaîne de texte, et intègre l'icône dans la page. -

Lorsque l'icône reçoit la focalisation, elle affiche le texte dans une boîte d'information contextuelle pour fournir d'autres informations contextuelles.

+Lorsque l'icône reçoit la focalisation, elle affiche le texte dans une boîte d'information contextuelle pour fournir d'autres informations contextuelles. -

Pour commencer, dans notre fichier JavaScript, nous définissons une classe appelée PopUpInfo qui étend {{domxref("HTMLElement")}}. Les éléments personnalisés indépendants étendent presque toujours HTMLElement.

+Pour commencer, dans notre fichier JavaScript, nous définissons une classe appelée `PopUpInfo` qui étend {{domxref("HTMLElement")}}. Les éléments personnalisés indépendants étendent presque toujours `HTMLElement`. -
class PopUpInfo extends HTMLElement {
+```js
+class PopUpInfo extends HTMLElement {
   constructor() {
     // Toujours appeler "super" d'abord dans le constructeur
     super();
@@ -80,13 +79,15 @@ translation_of: Web/Web_Components/Using_custom_elements
     // Ecrire la fonctionnalité de l'élément ici
     ...
   }
-}
+} +``` -

On y trouve la définition {{jsxref("Classes.constructor","constructor")}} de la classe, qui commence comme toujours par appeler super(), afin que la chaîne de prototype correcte soit définie.

+On y trouve la définition {{jsxref("Classes.constructor","constructor")}} de la classe, qui commence comme toujours par appeler super(), afin que la chaîne de prototype correcte soit définie. -

Dans le constructeur, nous définissons toutes les fonctionnalités que l'élément aura lorsqu'une instance de celui-ci sera instanciée. Dans ce cas, nous attachons une racine fantôme à l'élément personnalisé, nous utilisons une manipulation DOM pour créer la structure DOM interne de l'élément - qui est ensuite attachée à la racine fantôme ; et finalement, nous attachons du CSS à la racine fantôme pour la mettre en forme.

+Dans le constructeur, nous définissons toutes les fonctionnalités que l'élément aura lorsqu'une instance de celui-ci sera instanciée. Dans ce cas, nous attachons une racine fantôme à l'élément personnalisé, nous utilisons une manipulation DOM pour créer la structure DOM interne de l'élément - qui est ensuite attachée à la racine fantôme ; et finalement, nous attachons du CSS à la racine fantôme pour la mettre en forme. -
// Création d'une racine fantôme
+```js
+// Création d'une racine fantôme
 var shadow = this.attachShadow({mode: 'open'});
 
 // Création des spans
@@ -124,29 +125,33 @@ style.textContent = '.wrapper {' +
 shadow.appendChild(style);
 shadow.appendChild(wrapper);
 wrapper.appendChild(icon);
-wrapper.appendChild(info);
+wrapper.appendChild(info); +``` -

Enfin, nous enregistrons notre élément personnalisé dans le CustomElementRegistry à l'aide de la méthode define() mentionnée précédemment ; dans les paramètres, nous spécifions le nom de l'élément, puis le nom de la classe qui définit sa fonctionnalité :

+Enfin, nous enregistrons notre élément personnalisé dans le `CustomElementRegistry` à l'aide de la méthode `define()` mentionnée précédemment ; dans les paramètres, nous spécifions le nom de l'élément, puis le nom de la classe qui définit sa fonctionnalité : -
customElements.define('popup-info', PopUpInfo);
+```js +customElements.define('popup-info', PopUpInfo); +``` -

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

+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)
+```html
+
+  back of your card.">
+```
 
-

-
Note : Vous pouvez voir le full JavaScript source code ici.

-

+> **Note :** Vous pouvez voir le [full JavaScript source code](https://github.com/mdn/web-components-examples/blob/master/popup-info-box-web-component/main.js) ici.
 
-
Eléments intégrés personnalisés

+### Eléments intégrés personnalisés
 
-
Jetons maintenant un coup d'œil à un autre exemple d'élément intégré - expanding-list (voir aussi en direct). Cela transforme n'importe quelle liste non ordonnée en un menu déployable/refermable.

+Jetons maintenant un coup d'œil à un autre exemple d'élément intégré - [expanding-list](https://github.com/mdn/web-components-examples/tree/master/expanding-list-web-component) ([voir aussi en direct](https://mdn.github.io/web-components-examples/expanding-list-web-component/)). Cela transforme n'importe quelle liste non ordonnée en un menu déployable/refermable.
 
-
Tout d'abord, nous définissons la classe de notre élément, de la même manière que précédemment :

+Tout d'abord, nous définissons la classe de notre élément, de la même manière que précédemment :
 
-
class ExpandingList extends HTMLUListElement {
+```js
+class ExpandingList extends HTMLUListElement {
   constructor() {
     // Toujours appeler "super" d'abord dans le constructeur
     super();
@@ -155,58 +160,64 @@ wrapper.appendChild(info);

 
     ...
   }
-}
+} +``` -

Nous n'expliquerons pas en détail la fonctionnalité de l'élément ici, mais vous pouvez découvrir comment elle fonctionne en regardant le code source. La seule vraie différence ici est que notre élément étend l'interface {{domxref("HTMLUListElement")}}, et non {{domxref("HTMLElement")}}. Il a donc toutes les caractéristiques d'un élément {{htmlelement ("ul")}} avec la fonctionnalité que nous définissons par dessus, plutôt que d'être un élément indépendant. C'est ce qui en fait un élément intégré personnalisé plutôt qu'un élément indépendant.

+Nous n'expliquerons pas en détail la fonctionnalité de l'élément ici, mais vous pouvez découvrir comment elle fonctionne en regardant le code source. La seule vraie différence ici est que notre élément étend l'interface {{domxref("HTMLUListElement")}}, et non {{domxref("HTMLElement")}}. Il a donc toutes les caractéristiques d'un élément {{htmlelement ("ul")}} avec la fonctionnalité que nous définissons par dessus, plutôt que d'être un élément indépendant. C'est ce qui en fait un élément intégré personnalisé plutôt qu'un élément indépendant. -

Ensuite, nous enregistrons l'élément en utilisant la méthode define() comme précédemment, sauf que cette fois, il comprend également un objet options qui détaille l'élément dont notre élément personnalisé hérite :

+Ensuite, nous enregistrons l'élément en utilisant la méthode `define()` comme précédemment, sauf que cette fois, il comprend également un objet options qui détaille l'élément dont notre élément personnalisé hérite : -
customElements.define('expanding-list', ExpandingList, { extends: "ul" });
+```js +customElements.define('expanding-list', ExpandingList, { extends: "ul" }); +``` -

L'utilisation de l'élément intégré dans un document web se présente également de façon quelque peu différente :

+L'utilisation de l'élément intégré dans un document web se présente également de façon quelque peu différente : -
<ul is="expanding-list">
+```html
+
    
 
   ...
 
-</ul>
+ +``` -

Vous utilisez l'élément <ul> comme d'habitude, mais vous spécifiez le nom de l'élément personnalisé dans l'attribut is.

+Vous utilisez l'élément `
    ` comme d'habitude, mais vous spécifiez le nom de l'élément personnalisé dans l'attribut `is`. -
    -

    Note : à nouveau, vous pouvez voir le JavaScript source code complet ici.

    -
    +> **Note :** à nouveau, vous pouvez voir le [JavaScript source code](https://github.com/mdn/web-components-examples/blob/master/expanding-list-web-component/main.js) complet ici. -

    Utilisation des rappels de cycle de vie

    +## Utilisation des rappels de cycle de vie -

    Vous pouvez définir plusieurs rappels différents dans le constructeur d'un élément personnalisé, qui se déclenchent à différents points du cycle de vie de l'élément :

    +Vous pouvez définir plusieurs rappels différents dans le constructeur d'un élément personnalisé, qui se déclenchent à différents points du cycle de vie de l'élément : -
      -
    • connectedCallback : appelé lorsque l'élément personnalisé est connecté pour la première fois au DOM du document ;
      • -
    • disconnectedCallback : appelé lorsque l'élément personnalisé est déconnecté du DOM du document ;
      • -
    • adoptedCallback : appelé lorsque l'élément personnalisé est déplacé vers un nouveau document ;
      • -
    • attributeChangedCallback : appelé lorsque l'un des attributs de l'élément personnalisé est ajouté, supprimé ou modifié.
      • -
    +- connectedCallback : appelé lorsque l'élément personnalisé est connecté pour la première fois au DOM du document ; +- disconnectedCallback : appelé lorsque l'élément personnalisé est déconnecté du DOM du document ; +- adoptedCallback : appelé lorsque l'élément personnalisé est déplacé vers un nouveau document ; +- attributeChangedCallback : appelé lorsque l'un des attributs de l'élément 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'exécuter en direct). C'est un exemple trivial qui génère simplement un carré coloré de taille fixe sur la page. L'élément personnalisé ressemble à ceci :

    +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](https://github.com/mdn/web-components-examples/tree/master/life-cycle-callbacks) ([le voir s'exécuter en direct](https://mdn.github.io/web-components-examples/life-cycle-callbacks/)). C'est un exemple trivial qui génère simplement un carré coloré de taille fixe sur la page. L'élément personnalisé ressemble à ceci : -
    <custom-square l="100" c="red"></custom-square>
    +```html + +``` -

    Le constructeur de classe est vraiment simple - ici, nous attachons un DOM à l'élément, puis nous attachons les éléments vides {{htmlelement("div")}} et {{htmlelement("style")}} à la racine fantôme :

    +Le constructeur de classe est vraiment simple - ici, nous attachons un DOM à l'élément, puis nous attachons les éléments vides {{htmlelement("div")}} et {{htmlelement("style")}} à la racine fantôme : -
    var shadow = this.attachShadow({mode: 'open'});
+```js
+var shadow = this.attachShadow({mode: 'open'});
 
 var div = document.createElement('div');
 var style = document.createElement('style');
 shadow.appendChild(style);
-shadow.appendChild(div);
    +shadow.appendChild(div); +``` -

    La fonction clé dans cet exemple est updateStyle() : elle prend un élément, récupère sa racine fantôme, retrouve son élément <style>, et ajoute {{cssxref("width")}}, {{cssxref("height")}}, et {{cssxref("background-color")}} au style.

    +La fonction clé dans cet exemple est `updateStyle()` : elle prend un élément, récupère sa racine fantôme, retrouve son élément `