From 7d233a6bff46d1e69c6eb3726d4db6a48ac5934a Mon Sep 17 00:00:00 2001 From: julieng Date: Thu, 11 Nov 2021 08:43:19 +0100 Subject: move *.html to *.md --- files/fr/web/web_components/index.html | 112 ------- files/fr/web/web_components/index.md | 112 +++++++ .../using_custom_elements/index.html | 251 --------------- .../web_components/using_custom_elements/index.md | 251 +++++++++++++++ .../web/web_components/using_shadow_dom/index.html | 217 ------------- .../web/web_components/using_shadow_dom/index.md | 217 +++++++++++++ .../using_templates_and_slots/index.html | 343 --------------------- .../using_templates_and_slots/index.md | 343 +++++++++++++++++++++ 8 files changed, 923 insertions(+), 923 deletions(-) delete mode 100644 files/fr/web/web_components/index.html create mode 100644 files/fr/web/web_components/index.md delete mode 100644 files/fr/web/web_components/using_custom_elements/index.html create mode 100644 files/fr/web/web_components/using_custom_elements/index.md delete mode 100644 files/fr/web/web_components/using_shadow_dom/index.html create mode 100644 files/fr/web/web_components/using_shadow_dom/index.md delete mode 100644 files/fr/web/web_components/using_templates_and_slots/index.html create mode 100644 files/fr/web/web_components/using_templates_and_slots/index.md (limited to 'files/fr/web/web_components') diff --git a/files/fr/web/web_components/index.html b/files/fr/web/web_components/index.html deleted file mode 100644 index 61c90c9a2a..0000000000 --- a/files/fr/web/web_components/index.html +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Web Components -slug: Web/Web_Components -tags: - - Composants Web -translation_of: Web/Web_Components ---- -

{{DefaultAPISidebar("Web Components")}}{{ draft }}

- -

Les Composants Web sont constitués de plusieurs technologies distinctes permettant de créer des composants d'interface graphique personnalisés et réutilisables, qui ont été créés en utilisant des technologies web libres. Ils font partie du navigateur, et donc ne nécessitent pas de bibliothèque externe comme jQuery ou Dojo. Un Composant Web existant peut être utilisé sans l'écriture de code, en ajoutant simplement une déclaration d'importation à une page HTML. Les Composants Web utilisent les nouvelles capacités standard de navigateur, ou celles en cours de développement.

- -

Concepts et utilisation

- -

En tant que développeurs, nous savons tous à quel point la réutilisation de code est une bonne chose. Malgré cela, historiquement, il a toujours été difficile de réutiliser les languages balisés. Prenez par exemple tous ces éléments complexes en HTML que vous avez créés et dû répéter dans vos applications avec le risque que votre code devienne incompréhensible.

- -

Les composants Web ont pour but de résoudre ce problème et consistent en 3 technologies qui peuvent être utilisées ensemble pour créer des éléments réutilisables, encapsulés, versatiles et sans risquer une collision avec d'autre morceaux de code.

- - - -

Au début de la spécification, il y avait aussi la technologie HTML Imports. Celle-ci servait à packager ses composants (CSS, JavaScript, etc.) et permettre leur intégration dans d'autres pages. Elle a néanmoins été abandonnée au profit des imports javascript qui permettent la même chose en utilisant une syntaxe plus moderne.

- -

La description ci-dessus fonctionne assez bien à l'heure actuelle, mais cela laisse de côté plusieurs choses pour lesquelles les Composants Web pourraient être utilisés. Avec un Composant Web, vous pouvez faire presque tout ce qui peut être fait en HTML, CSS et JavaScript, et celui-ci peut devenir un élément réutilisable facilement.

- -

Il y a parfois une certaine confusion concernant les Composants Web et Google Polymer. Polymer est un framework qui repose sur la technologie des Composants Web. Vous pouvez faire et utiliser des Composants Web sans Polymer.

- -

Généralement, l'approche basique pour la création d'un composant Web est la suivante:

- -
    -
  1. Créer une classe dans laquelle est spécifié la fonctionnalité du composant Web en utilisant la syntaxe de classe ECMAScript 2015 (voir les Classes pour de plus amples informations).
    2. -
  2. Enregistrer le nouvel élément personnalisé en utilisant la méthode {{domxref("CustomElementRegistry.define()")}}, avec en paramètre le nom de l'élément à définir, la classe ou la fonction dans laquelle la fonctionnalité est spécifiée, et optionnellement, de quel élément celui-ci hérite-t-il.
    3. -
  3. Si nécessaire, connecter un shadow DOM à l'élément personnalisé en utilisant la méthode {{domxref("Element.attachShadow()")}}. Ajouter les éléments-fils, les écouteurs d'événements, etc., au shadow DOM en utilisant les méthodes DOM usuelles.
    4. -
  4. Si nécessaire, définir un template HTML en utilisant {{htmlelement("template")}} et {{htmlelement("slot")}}. Toujours en utilisant les méthodes DOM usuelles pour cloner le template et le connecter au shadow DOM.
    5. -
  5. Utiliser l'élément personnalisé à l'endroit désiré sur la page, comme tous les autres éléments HTML.
    6. -
- -
-

Note : Les Composants Web ne sont pas encore pleinement mis en œuvre dans tous les navigateurs, et pour les utiliser dès maintenant dans la plupart des navigateurs (janvier 2015), vous devrez probablement utiliser des polyfills (ce sont des bibliothèques JavaScript destinées à émuler des fonctionnalités qui ne sont pas encore implémentées nativement dans les navigateurs). Les polyfills sont disponibles dans le projet Google Polymer. Pour savoir quels navigateurs implémentent les Composants Web, voir Are We Componentized Yet?

-
- - -

Les spécifications des Composants Web définissent les éléments suivants :

- - - -

Activer les Web Components dans Firefox

- -

Les capacités des Web Components sont désactivées par défaut dans Firefox. Pour les activer, allez sur la page about:config et rejetez toutes les alertes qui apparaissent. Cherchez ensuite la préférence nommée dom.webcomponents.enabled, et changez la à true par un double clic.

- -

Firefox enable web components

- -

Spécifications

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SpécificationStatutCommentaire
{{SpecName('Custom Elements', "", "")}}{{Spec2('Custom Elements')}}
{{SpecName('HTML WHATWG','/scripting-1.html#the-template-element','template element')}}{{Spec2('HTML WHATWG')}}Pas de changement
{{SpecName('HTML5 W3C','/scripting-1.html#the-template-element','template element')}}{{Spec2('HTML5 W3C')}}Définition initiale
{{SpecName('Shadow DOM', "", "")}}{{Spec2('Shadow DOM')}}
{{SpecName('HTML Imports', "", "")}}{{Spec2('HTML Imports')}}
{{SpecName("CSS Scope", "", "")}}{{Spec2('CSS Scope')}}
diff --git a/files/fr/web/web_components/index.md b/files/fr/web/web_components/index.md new file mode 100644 index 0000000000..61c90c9a2a --- /dev/null +++ b/files/fr/web/web_components/index.md @@ -0,0 +1,112 @@ +--- +title: Web Components +slug: Web/Web_Components +tags: + - Composants Web +translation_of: Web/Web_Components +--- +

{{DefaultAPISidebar("Web Components")}}{{ draft }}

+ +

Les Composants Web sont constitués de plusieurs technologies distinctes permettant de créer des composants d'interface graphique personnalisés et réutilisables, qui ont été créés en utilisant des technologies web libres. Ils font partie du navigateur, et donc ne nécessitent pas de bibliothèque externe comme jQuery ou Dojo. Un Composant Web existant peut être utilisé sans l'écriture de code, en ajoutant simplement une déclaration d'importation à une page HTML. Les Composants Web utilisent les nouvelles capacités standard de navigateur, ou celles en cours de développement.

+ +

Concepts et utilisation

+ +

En tant que développeurs, nous savons tous à quel point la réutilisation de code est une bonne chose. Malgré cela, historiquement, il a toujours été difficile de réutiliser les languages balisés. Prenez par exemple tous ces éléments complexes en HTML que vous avez créés et dû répéter dans vos applications avec le risque que votre code devienne incompréhensible.

+ +

Les composants Web ont pour but de résoudre ce problème et consistent en 3 technologies qui peuvent être utilisées ensemble pour créer des éléments réutilisables, encapsulés, versatiles et sans risquer une collision avec d'autre morceaux de code.

+ + + +

Au début de la spécification, il y avait aussi la technologie HTML Imports. Celle-ci servait à packager ses composants (CSS, JavaScript, etc.) et permettre leur intégration dans d'autres pages. Elle a néanmoins été abandonnée au profit des imports javascript qui permettent la même chose en utilisant une syntaxe plus moderne.

+ +

La description ci-dessus fonctionne assez bien à l'heure actuelle, mais cela laisse de côté plusieurs choses pour lesquelles les Composants Web pourraient être utilisés. Avec un Composant Web, vous pouvez faire presque tout ce qui peut être fait en HTML, CSS et JavaScript, et celui-ci peut devenir un élément réutilisable facilement.

+ +

Il y a parfois une certaine confusion concernant les Composants Web et Google Polymer. Polymer est un framework qui repose sur la technologie des Composants Web. Vous pouvez faire et utiliser des Composants Web sans Polymer.

+ +

Généralement, l'approche basique pour la création d'un composant Web est la suivante:

+ +
    +
  1. Créer une classe dans laquelle est spécifié la fonctionnalité du composant Web en utilisant la syntaxe de classe ECMAScript 2015 (voir les Classes pour de plus amples informations).
    2. +
  2. Enregistrer le nouvel élément personnalisé en utilisant la méthode {{domxref("CustomElementRegistry.define()")}}, avec en paramètre le nom de l'élément à définir, la classe ou la fonction dans laquelle la fonctionnalité est spécifiée, et optionnellement, de quel élément celui-ci hérite-t-il.
    3. +
  3. Si nécessaire, connecter un shadow DOM à l'élément personnalisé en utilisant la méthode {{domxref("Element.attachShadow()")}}. Ajouter les éléments-fils, les écouteurs d'événements, etc., au shadow DOM en utilisant les méthodes DOM usuelles.
    4. +
  4. Si nécessaire, définir un template HTML en utilisant {{htmlelement("template")}} et {{htmlelement("slot")}}. Toujours en utilisant les méthodes DOM usuelles pour cloner le template et le connecter au shadow DOM.
    5. +
  5. Utiliser l'élément personnalisé à l'endroit désiré sur la page, comme tous les autres éléments HTML.
    6. +
+ +
+

Note : Les Composants Web ne sont pas encore pleinement mis en œuvre dans tous les navigateurs, et pour les utiliser dès maintenant dans la plupart des navigateurs (janvier 2015), vous devrez probablement utiliser des polyfills (ce sont des bibliothèques JavaScript destinées à émuler des fonctionnalités qui ne sont pas encore implémentées nativement dans les navigateurs). Les polyfills sont disponibles dans le projet Google Polymer. Pour savoir quels navigateurs implémentent les Composants Web, voir Are We Componentized Yet?

+
+ + +

Les spécifications des Composants Web définissent les éléments suivants :

+ + + +

Activer les Web Components dans Firefox

+ +

Les capacités des Web Components sont désactivées par défaut dans Firefox. Pour les activer, allez sur la page about:config et rejetez toutes les alertes qui apparaissent. Cherchez ensuite la préférence nommée dom.webcomponents.enabled, et changez la à true par un double clic.

+ +

Firefox enable web components

+ +

Spécifications

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SpécificationStatutCommentaire
{{SpecName('Custom Elements', "", "")}}{{Spec2('Custom Elements')}}
{{SpecName('HTML WHATWG','/scripting-1.html#the-template-element','template element')}}{{Spec2('HTML WHATWG')}}Pas de changement
{{SpecName('HTML5 W3C','/scripting-1.html#the-template-element','template element')}}{{Spec2('HTML5 W3C')}}Définition initiale
{{SpecName('Shadow DOM', "", "")}}{{Spec2('Shadow DOM')}}
{{SpecName('HTML Imports', "", "")}}{{Spec2('HTML Imports')}}
{{SpecName("CSS Scope", "", "")}}{{Spec2('CSS Scope')}}
diff --git a/files/fr/web/web_components/using_custom_elements/index.html b/files/fr/web/web_components/using_custom_elements/index.html deleted file mode 100644 index e01061d005..0000000000 --- a/files/fr/web/web_components/using_custom_elements/index.html +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: Utilisation d'éléments personnalisés -slug: Web/Web_Components/Using_custom_elements -tags: - - Classes - - Guide - - Web Components - - autonomous - - custom elements - - customized -translation_of: Web/Web_Components/Using_custom_elements ---- -
{{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.

- -
-

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

- -

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 :

- - - -

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

- -
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'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 {
-  constructor() {
-    // Toujours appeler "super" d'abord dans le constructeur
-    super();
-
-    // Ecrire la fonctionnalité de l'élément ici
-
-    ...
-  }
-}
- -

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.

- -

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

- - - -

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.

- -

É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.

- -

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.

- -
class PopUpInfo extends HTMLElement {
-  constructor() {
-    // Toujours appeler "super" d'abord dans le constructeur
-    super();
-
-    // 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.

- -

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
-var shadow = this.attachShadow({mode: 'open'});
-
-// Création 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;
-
-// Insérer l'icône
-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);
-
-// Création du CSS à appliquer au dom fantôme
-var style = document.createElement('style');
-
-style.textContent = '.wrapper {' +
-// CSS tronqué pour la concision
-
-// Attacher les éléments créés au dom fantôme
-
-shadow.appendChild(style);
-shadow.appendChild(wrapper);
-wrapper.appendChild(icon);
-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é :

- -
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.">
- -
-

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

-
- -

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.

- -

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 {
-  constructor() {
-    // Toujours appeler "super" d'abord dans le constructeur
-    super();
-
-    // Ecrire la fonctionnalité de l'élément ici
-
-    ...
-  }
-}
- -

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 :

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

- -
<ul is="expanding-list">
-
-  ...
-
-</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.

- -
-

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

-
- -

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 :

- - - -

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 :

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

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'});
-
-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 é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.

- -
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 réelles sont toutes gérées par les rappels du cycle de vie, qui sont placés dans le constructeur. Le connectedCallback() s'exécute quand l'élément est ajouté au DOM : ici, nous exécutons la fonction updateStyle() pour nous assurer que le carré est mis en forme comme défini 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'élément est supprimé du DOM ou déplacé 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 exécuté chaque fois que l'un des attributs de l'élément est modifié d'une façon ou d'une autre. Comme vous pouvez le voir à partir de ses propriétés, 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 exécutons 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 déclencher le rappel attributeChangedCallback() lorsqu'un attribut change, vous devez observer les attributs. Cela est réalisé en appelant le getter observedAttributes() dans le constructeur, en incluant à l'intérieur une instruction return qui retourne 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 début du constructeur.

- -
-

Note : vous pouvez trouver le full JavaScript source .

-
diff --git a/files/fr/web/web_components/using_custom_elements/index.md b/files/fr/web/web_components/using_custom_elements/index.md new file mode 100644 index 0000000000..e01061d005 --- /dev/null +++ b/files/fr/web/web_components/using_custom_elements/index.md @@ -0,0 +1,251 @@ +--- +title: Utilisation d'éléments personnalisés +slug: Web/Web_Components/Using_custom_elements +tags: + - Classes + - Guide + - Web Components + - autonomous + - custom elements + - customized +translation_of: Web/Web_Components/Using_custom_elements +--- +
{{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.

+ +
+

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

+ +

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 :

+ + + +

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

+ +
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'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 {
+  constructor() {
+    // Toujours appeler "super" d'abord dans le constructeur
+    super();
+
+    // Ecrire la fonctionnalité de l'élément ici
+
+    ...
+  }
+}
+ +

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.

+ +

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

+ + + +

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.

+ +

É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.

+ +

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.

+ +
class PopUpInfo extends HTMLElement {
+  constructor() {
+    // Toujours appeler "super" d'abord dans le constructeur
+    super();
+
+    // 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.

+ +

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
+var shadow = this.attachShadow({mode: 'open'});
+
+// Création 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;
+
+// Insérer l'icône
+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);
+
+// Création du CSS à appliquer au dom fantôme
+var style = document.createElement('style');
+
+style.textContent = '.wrapper {' +
+// CSS tronqué pour la concision
+
+// Attacher les éléments créés au dom fantôme
+
+shadow.appendChild(style);
+shadow.appendChild(wrapper);
+wrapper.appendChild(icon);
+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é :

+ +
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.">
+ +
+

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

+
+ +

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.

+ +

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 {
+  constructor() {
+    // Toujours appeler "super" d'abord dans le constructeur
+    super();
+
+    // Ecrire la fonctionnalité de l'élément ici
+
+    ...
+  }
+}
+ +

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 :

+ +
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 :

+ +
<ul is="expanding-list">
+
+  ...
+
+</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.

+ +
+

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

+
+ +

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 :

+ + + +

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 :

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

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'});
+
+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 é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.

+ +
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 réelles sont toutes gérées par les rappels du cycle de vie, qui sont placés dans le constructeur. Le connectedCallback() s'exécute quand l'élément est ajouté au DOM : ici, nous exécutons la fonction updateStyle() pour nous assurer que le carré est mis en forme comme défini 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'élément est supprimé du DOM ou déplacé 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 exécuté chaque fois que l'un des attributs de l'élément est modifié d'une façon ou d'une autre. Comme vous pouvez le voir à partir de ses propriétés, 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 exécutons 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 déclencher le rappel attributeChangedCallback() lorsqu'un attribut change, vous devez observer les attributs. Cela est réalisé en appelant le getter observedAttributes() dans le constructeur, en incluant à l'intérieur une instruction return qui retourne 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 début du constructeur.

+ +
+

Note : vous pouvez trouver le full JavaScript source .

+
diff --git a/files/fr/web/web_components/using_shadow_dom/index.html b/files/fr/web/web_components/using_shadow_dom/index.html deleted file mode 100644 index ca14a4ca77..0000000000 --- a/files/fr/web/web_components/using_shadow_dom/index.html +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: Utiliser le shadow DOM -slug: Web/Web_Components/Using_shadow_DOM -tags: - - API - - DOM - - Guide - - Web Components - - shadow dom -translation_of: Web/Web_Components/Using_shadow_DOM ---- -
{{DefaultAPISidebar("Web Components")}}
- -

Un aspect important des composants web est l'encapsulation — être capable de garder la structure de balisage, le style et le comportement cachés et séparés du reste de code de la page tel que différentes parties n'entrent pas en conflit et que le code puisse rester agréable et propre. L'API Shadow DOM est un moyen d'y parvenir, fournissant une manière d'associer à un élément un DOM séparé et caché. Cet article couvre les bases de l'utilisation du DOM fantôme.

- -
-

Note : L'API Shadow DOM est supportée par défaut dans Firefox (63 et suivants), Chrome, Opera, et Safari. Le nouveau Edge basé sur Chromium (75 et suivants) le supportent aussi; le vieux Edge ne le supporte.

-
- -

Vue de haut niveau

- -

Cet article suppose que vous êtes déjà familier avec le concept de DOM (Document Object Model) — une structure arborescente de nœuds connectés représentant les différents éléments et chaines de textes apparaissant dans un document balisé (généralement un document HTML dans le cas de documents web). Par exemple, considérez le fragment HTML suivant :

- -
<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <title>Simple exemple de DOM</title>
-  </head>
-  <body>
-    <section>
-      <img src="dinosaur.png" alt="Un tyrannosaurus Rex rouge : un dinosaure bipède se tenant debout comme un humain, avec de petits bras et une large gueule à nombreuses dents tranchantes.">
-      <p>Nous ajouterons ici un lien vers la <a href="https://www.mozilla.org/">page d'accueil de Mozilla</a></p>
-    </section>
-  </body>
-</html>
- -

Ce fragment produit la structure DOM suivante :

- -

- -

Le DOM fantôme permet à des arbres DOM cachés d'être associés à des éléments de l'arbre DOM principal — cet arbre DOM fantôme s'ouvre avec une racine fantôme placée sous n'importe quel élément voulu, de la même manière que dans le DOM normal.

- -

Version SVG du diagramme montrant l'interaction entre le document, la racine fantôme et l'hôte fantôme.

- -

Il y a quelques termes de la terminologie du DOM fantôme que vous devez connaitre :

- - - -

Vous pouvez affecter les nœuds du DOM fantôme exactement de la même manière que pour les nœuds du DOM principal — par exemple en leur ajoutant des éléments enfants ou en leur définissant des attributs, en stylisant des nœuds individuels au moyen de element.style.propriete, ou en ajoutant du style à l'arbre DOM fantôme entier via une balise <style>. La différence est que le code au sein du DOM fantôme ne peut affecter aucun élément en dehors de son arbre, permettant de mettre en œuvre une encapsulation très commode.

- -

Notez que le DOM fantôme n'est pas une nouvelle chose du tout — les navigateurs l'ont utilisé depuis longtemps pour encapsuler la structure interne d'un élément. Pensez par exemple à un élément <video>, avec les contrôles par défaut du navigateur apparents. Tout ce que vous voyez dans le DOM est l'élément <video>, mais il contient plusieurs boutons et autres contrôles au sein de son DOM fantôme. La spécification du DOM fantôme a été conçue de telle manière que vous êtes autorisés à manipuler le DOM fantôme de vos propres éléments personnalisés.

- -

Usage basique

- -

Vous pouvez associer une racine fantôme à tout élément en utilisant la méthode Element.attachShadow(). Elle prend en paramètres un objet d'options contenant une option — mode — ayant pour valeur open (ouvert) ou closed (fermé) :

- -
let fantome = element.attachShadow({mode: 'open'});
-let fantome = element.attachShadow({mode: 'closed'});
- -

open signifie que vous pouvez accéder au DOM fantôme en utilisant du JavaScript écrit dans le contexte de la page principale, par exemple en utilisant la propriété Element.shadowRoot :

- -
let monDomFantome = monElementPerso.shadowRoot;
- -

Si vous associez une racine fantôme à un élément personnalisé avec la propriété mode définie à closed, vous ne serez pas autorisé à accéder au DOM fantôme depuis l'extérieur — monElementPerso.shadowRoot retournera null. C'est le cas avec les éléments natifs contenant des DOM fantômes tels que <video>.

- -
-

Note : Comme montre cet article de blog (en anglais), il est actuellement assez simple de pénétrer les DOM fantômes fermés, et les cacher complètement n'en vaut souvent pas la peine.

-
- -

Si vous voulez associer un DOM fantôme à un élément personnalisé en tant que partie de son constructeur (de loin la plus utile application du DOM fantôme), vous devriez utiliser quelque instruction comme :

- -
let shadow = this.attachShadow({mode: 'open'});
- -

Lorsque vous avez associé un DOM fantôme à un élément, le manipuler consiste seulement à utiliser les API du DOM telles que vous les utilisez pour manipuler le DOM principal :

- -
let paragraph = document.createElement('p');
-shadow.appendChild(paragraph);
-// etc.
- -

Démonstration au travers d'un exemple simple

- -

Maintenant, visitons un exemple simple pour faire une démonstration du DOM fantôme en action au sein d'un élément personnalisé — <popup-info-box> (en voir aussi un exemple dynamique). Il prend une icône et une chaîne de caractères et intègre l'image dans la page. Quand l'icône obtient l'attention (:focus), le texte s'affiche dans une fenêtre indépendante pour fournir plus d'informations contextuelles. Pour commencer, nous définissons dans notre fichier JavaScript une classe appelée PopUpInfo, qui étend HTMLElement :

- -
class PopUpInfo extends HTMLElement {
-  constructor() {
-    // Toujours appeler super en premier dans le constructeur
-    super();
-
-    // Écrire les fonctionnalités de l'élément ici
-
-    ...
-  }
-}
- -

Au sein de la définition de la classe, nous créons le constructeur de l'élément, qui définit toutes les fonctionnalités que l'élément aura lorsqu'une instance est créée.

- -

Créer la racine fantôme

- -

Nous associons d'abord une racine fantôme à l'élément personnalisé :

- -
// Créer une racine fantôme
-let fantome = this.attachShadow({mode: 'open'});
- -

Créer la structure du DOM fantôme

- -

Ensuite, nous utilisons des outils de manipulation du DOM pour créer la structure interne du DOM fantôme de notre élément :

- -
// Créer les <span>
-let wrapper = document.createElement('span');
-wrapper.setAttribute('class','wrapper');
-let icon = document.createElement('span');
-icon.setAttribute('class','icon');
-icon.setAttribute('tabindex', 0);
-let info = document.createElement('span');
-info.setAttribute('class','info');
-
-// Prendre le contenu de l'attribut et le placer à l'intérieur du span info
-let text = this.getAttribute('text');
-info.textContent = text;
-
-// Insérer l'icône
-let imgUrl;
-if(this.hasAttribute('img')) {
-  imgUrl = this.getAttribute('img');
-} else {
-  imgUrl = 'img/default.png';
-}
-let img = document.createElement('img');
-img.src = imgUrl;
-icon.appendChild(img);
- -

Styliser le DOM fantôme

- -

Après cela, nous créons un élément <style> et nous ajoutons du CSS pour personnaliser notre arbre DOM :

- -
// Créer quelque CSS à appliquer au dom fantôme
-let style = document.createElement('style');
-
-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;
-}`;
- -

Associer le DOM fantôme à la racine fantôme

- -

L'étape finale est d'associer tous les éléments créés à la racine fantôme :

- -
// Associer les éléments créés au dom fantôme
-shadow.appendChild(style);
-shadow.appendChild(wrapper);
-wrapper.appendChild(icon);
-wrapper.appendChild(info);
- -

Utiliser notre élément personnalisé

- -

Une fois que la classe est définie, utiliser l'élément est aussi simple que de le définir, et l'ajouter sur la page, comme expliqué dans Utiliser les éléments personnalisés :

- -
// Définit le nouvel élément
-customElements.define('popup-info', PopUpInfo);
- -
<popup-info img="img/alt.png" text="Le code de validation de votre carte (CVC) est un élément de sécurité
-  supplémentaire. Il s'agit des 3 ou 4 derniers chiffres figurant au dos de votre carte.">
- -

Styles internes ou styles externes

- -

Dans l'exemple précédent, nous appliquons du style au DOM fantôme en utilisant l'élément <style>, mais il est parfaitement possible de le faire en référençant une feuille de style externe avec un élément <link> si vous le préférez.

- -

Par exemple, regardez ce code tiré de l'exemple popup-info-box-external-stylesheet (voir le code source) :

- -
// Appliquer les styles externes au dom fantôme
-const linkElem = document.createElement('link');
-linkElem.setAttribute('rel', 'stylesheet');
-linkElem.setAttribute('href', 'style.css');
-
-// Associer l'élément créé au dom fantôme
-shadow.appendChild(linkElem);
- -

Notez que les éléments <link> ne bloquent pas la peinture de la racine fantôme, donc il pourrait y avoir une latence où le contenu serait sans style (FOUC) pendant que la feuille de style se charge.

- -

De nombreux navigateurs modernes implantent une optimisation pour les balises <style> clonées depuis un nœud commun ou qui ont des contenus identiques à fin de leur permettre de partager une unique liste de retour. Avec cette optimisation, la performance des styles externes et internes doivent être similaires.

- -

Voir aussi

- - diff --git a/files/fr/web/web_components/using_shadow_dom/index.md b/files/fr/web/web_components/using_shadow_dom/index.md new file mode 100644 index 0000000000..ca14a4ca77 --- /dev/null +++ b/files/fr/web/web_components/using_shadow_dom/index.md @@ -0,0 +1,217 @@ +--- +title: Utiliser le shadow DOM +slug: Web/Web_Components/Using_shadow_DOM +tags: + - API + - DOM + - Guide + - Web Components + - shadow dom +translation_of: Web/Web_Components/Using_shadow_DOM +--- +
{{DefaultAPISidebar("Web Components")}}
+ +

Un aspect important des composants web est l'encapsulation — être capable de garder la structure de balisage, le style et le comportement cachés et séparés du reste de code de la page tel que différentes parties n'entrent pas en conflit et que le code puisse rester agréable et propre. L'API Shadow DOM est un moyen d'y parvenir, fournissant une manière d'associer à un élément un DOM séparé et caché. Cet article couvre les bases de l'utilisation du DOM fantôme.

+ +
+

Note : L'API Shadow DOM est supportée par défaut dans Firefox (63 et suivants), Chrome, Opera, et Safari. Le nouveau Edge basé sur Chromium (75 et suivants) le supportent aussi; le vieux Edge ne le supporte.

+
+ +

Vue de haut niveau

+ +

Cet article suppose que vous êtes déjà familier avec le concept de DOM (Document Object Model) — une structure arborescente de nœuds connectés représentant les différents éléments et chaines de textes apparaissant dans un document balisé (généralement un document HTML dans le cas de documents web). Par exemple, considérez le fragment HTML suivant :

+ +
<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Simple exemple de DOM</title>
+  </head>
+  <body>
+    <section>
+      <img src="dinosaur.png" alt="Un tyrannosaurus Rex rouge : un dinosaure bipède se tenant debout comme un humain, avec de petits bras et une large gueule à nombreuses dents tranchantes.">
+      <p>Nous ajouterons ici un lien vers la <a href="https://www.mozilla.org/">page d'accueil de Mozilla</a></p>
+    </section>
+  </body>
+</html>
+ +

Ce fragment produit la structure DOM suivante :

+ +

+ +

Le DOM fantôme permet à des arbres DOM cachés d'être associés à des éléments de l'arbre DOM principal — cet arbre DOM fantôme s'ouvre avec une racine fantôme placée sous n'importe quel élément voulu, de la même manière que dans le DOM normal.

+ +

Version SVG du diagramme montrant l'interaction entre le document, la racine fantôme et l'hôte fantôme.

+ +

Il y a quelques termes de la terminologie du DOM fantôme que vous devez connaitre :

+ + + +

Vous pouvez affecter les nœuds du DOM fantôme exactement de la même manière que pour les nœuds du DOM principal — par exemple en leur ajoutant des éléments enfants ou en leur définissant des attributs, en stylisant des nœuds individuels au moyen de element.style.propriete, ou en ajoutant du style à l'arbre DOM fantôme entier via une balise <style>. La différence est que le code au sein du DOM fantôme ne peut affecter aucun élément en dehors de son arbre, permettant de mettre en œuvre une encapsulation très commode.

+ +

Notez que le DOM fantôme n'est pas une nouvelle chose du tout — les navigateurs l'ont utilisé depuis longtemps pour encapsuler la structure interne d'un élément. Pensez par exemple à un élément <video>, avec les contrôles par défaut du navigateur apparents. Tout ce que vous voyez dans le DOM est l'élément <video>, mais il contient plusieurs boutons et autres contrôles au sein de son DOM fantôme. La spécification du DOM fantôme a été conçue de telle manière que vous êtes autorisés à manipuler le DOM fantôme de vos propres éléments personnalisés.

+ +

Usage basique

+ +

Vous pouvez associer une racine fantôme à tout élément en utilisant la méthode Element.attachShadow(). Elle prend en paramètres un objet d'options contenant une option — mode — ayant pour valeur open (ouvert) ou closed (fermé) :

+ +
let fantome = element.attachShadow({mode: 'open'});
+let fantome = element.attachShadow({mode: 'closed'});
+ +

open signifie que vous pouvez accéder au DOM fantôme en utilisant du JavaScript écrit dans le contexte de la page principale, par exemple en utilisant la propriété Element.shadowRoot :

+ +
let monDomFantome = monElementPerso.shadowRoot;
+ +

Si vous associez une racine fantôme à un élément personnalisé avec la propriété mode définie à closed, vous ne serez pas autorisé à accéder au DOM fantôme depuis l'extérieur — monElementPerso.shadowRoot retournera null. C'est le cas avec les éléments natifs contenant des DOM fantômes tels que <video>.

+ +
+

Note : Comme montre cet article de blog (en anglais), il est actuellement assez simple de pénétrer les DOM fantômes fermés, et les cacher complètement n'en vaut souvent pas la peine.

+
+ +

Si vous voulez associer un DOM fantôme à un élément personnalisé en tant que partie de son constructeur (de loin la plus utile application du DOM fantôme), vous devriez utiliser quelque instruction comme :

+ +
let shadow = this.attachShadow({mode: 'open'});
+ +

Lorsque vous avez associé un DOM fantôme à un élément, le manipuler consiste seulement à utiliser les API du DOM telles que vous les utilisez pour manipuler le DOM principal :

+ +
let paragraph = document.createElement('p');
+shadow.appendChild(paragraph);
+// etc.
+ +

Démonstration au travers d'un exemple simple

+ +

Maintenant, visitons un exemple simple pour faire une démonstration du DOM fantôme en action au sein d'un élément personnalisé — <popup-info-box> (en voir aussi un exemple dynamique). Il prend une icône et une chaîne de caractères et intègre l'image dans la page. Quand l'icône obtient l'attention (:focus), le texte s'affiche dans une fenêtre indépendante pour fournir plus d'informations contextuelles. Pour commencer, nous définissons dans notre fichier JavaScript une classe appelée PopUpInfo, qui étend HTMLElement :

+ +
class PopUpInfo extends HTMLElement {
+  constructor() {
+    // Toujours appeler super en premier dans le constructeur
+    super();
+
+    // Écrire les fonctionnalités de l'élément ici
+
+    ...
+  }
+}
+ +

Au sein de la définition de la classe, nous créons le constructeur de l'élément, qui définit toutes les fonctionnalités que l'élément aura lorsqu'une instance est créée.

+ +

Créer la racine fantôme

+ +

Nous associons d'abord une racine fantôme à l'élément personnalisé :

+ +
// Créer une racine fantôme
+let fantome = this.attachShadow({mode: 'open'});
+ +

Créer la structure du DOM fantôme

+ +

Ensuite, nous utilisons des outils de manipulation du DOM pour créer la structure interne du DOM fantôme de notre élément :

+ +
// Créer les <span>
+let wrapper = document.createElement('span');
+wrapper.setAttribute('class','wrapper');
+let icon = document.createElement('span');
+icon.setAttribute('class','icon');
+icon.setAttribute('tabindex', 0);
+let info = document.createElement('span');
+info.setAttribute('class','info');
+
+// Prendre le contenu de l'attribut et le placer à l'intérieur du span info
+let text = this.getAttribute('text');
+info.textContent = text;
+
+// Insérer l'icône
+let imgUrl;
+if(this.hasAttribute('img')) {
+  imgUrl = this.getAttribute('img');
+} else {
+  imgUrl = 'img/default.png';
+}
+let img = document.createElement('img');
+img.src = imgUrl;
+icon.appendChild(img);
+ +

Styliser le DOM fantôme

+ +

Après cela, nous créons un élément <style> et nous ajoutons du CSS pour personnaliser notre arbre DOM :

+ +
// Créer quelque CSS à appliquer au dom fantôme
+let style = document.createElement('style');
+
+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;
+}`;
+ +

Associer le DOM fantôme à la racine fantôme

+ +

L'étape finale est d'associer tous les éléments créés à la racine fantôme :

+ +
// Associer les éléments créés au dom fantôme
+shadow.appendChild(style);
+shadow.appendChild(wrapper);
+wrapper.appendChild(icon);
+wrapper.appendChild(info);
+ +

Utiliser notre élément personnalisé

+ +

Une fois que la classe est définie, utiliser l'élément est aussi simple que de le définir, et l'ajouter sur la page, comme expliqué dans Utiliser les éléments personnalisés :

+ +
// Définit le nouvel élément
+customElements.define('popup-info', PopUpInfo);
+ +
<popup-info img="img/alt.png" text="Le code de validation de votre carte (CVC) est un élément de sécurité
+  supplémentaire. Il s'agit des 3 ou 4 derniers chiffres figurant au dos de votre carte.">
+ +

Styles internes ou styles externes

+ +

Dans l'exemple précédent, nous appliquons du style au DOM fantôme en utilisant l'élément <style>, mais il est parfaitement possible de le faire en référençant une feuille de style externe avec un élément <link> si vous le préférez.

+ +

Par exemple, regardez ce code tiré de l'exemple popup-info-box-external-stylesheet (voir le code source) :

+ +
// Appliquer les styles externes au dom fantôme
+const linkElem = document.createElement('link');
+linkElem.setAttribute('rel', 'stylesheet');
+linkElem.setAttribute('href', 'style.css');
+
+// Associer l'élément créé au dom fantôme
+shadow.appendChild(linkElem);
+ +

Notez que les éléments <link> ne bloquent pas la peinture de la racine fantôme, donc il pourrait y avoir une latence où le contenu serait sans style (FOUC) pendant que la feuille de style se charge.

+ +

De nombreux navigateurs modernes implantent une optimisation pour les balises <style> clonées depuis un nœud commun ou qui ont des contenus identiques à fin de leur permettre de partager une unique liste de retour. Avec cette optimisation, la performance des styles externes et internes doivent être similaires.

+ +

Voir aussi

+ + diff --git a/files/fr/web/web_components/using_templates_and_slots/index.html b/files/fr/web/web_components/using_templates_and_slots/index.html deleted file mode 100644 index 60a1052b93..0000000000 --- a/files/fr/web/web_components/using_templates_and_slots/index.html +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Utiliser les éléments template et slot -slug: Web/Web_Components/Using_templates_and_slots -translation_of: Web/Web_Components/Using_templates_and_slots -original_slug: Web/Web_Components/Utilisation_des_templates_et_des_slots ---- -
{{DefaultAPISidebar("Web Components")}}
- -

Cet article explique comment utiliser les éléments <template> et <slot> pour créer un modèle (template) flexible qui peut ensuite être utilisé pour alimenter le Shadow DOM d'un composant web.

- -

La vérité sur les modèmes

- -

Lorsqu'une structure de balises se répète sur une page web, il est judicieux d'utiliser un modèle plutôt que d'écrire cette même structure encore et encore. Il était déjà possible de le faire, mais l'élément HTML <template> (pris en charge par les navigateurs modernes) nous facilite la tâche. Cet élément et ce qu'il renferme n'est pas directement retranscrit dans le DOM, mais peut par contre toujours être manipulé avec JavaScript.

- -

Voyons un exemple simple :

- -
-<template id="my-paragraph">
-  <p>My paragraph</p>
-</template>
-
- -

Ceci restera invisible sur la page tant qu'aucune référence n'y sera faite dans le code JavaScript puis ajouté au DOM, en utilisant par exemple :

- -
-let template = document.getElementById('my-paragraph');
-let templateContent = template.content;
-document.body.appendChild(templateContent);
-
- -

Quoique trivial, cet exemple vous permet d'entrevoir l'interêt d'utiliser des modèles.

- -

Accorder modèles et composants web

- -

Les modèles sont utiles en eux-mêmes, mais ils fonctionnent encore mieux avec des composants web. Créons un composant web qui utilise notre modèle comme contenu de son Shadow DOM. Nous l'appellerons <my-paragraph> :

- -
-customElements.define('my-paragraph',
-  class extends HTMLElement {
-    constructor() {
-      super();
-      let template = document.getElementById('my-paragraph');
-      let templateContent = template.content;
-
-      const shadowRoot = this.attachShadow({mode: 'open'})
-        .appendChild(templateContent.cloneNode(true));
-  }
-})
- -

Le point important à noter est que l'on ajoute un clone du contenu du modèle à la racine du DOM, créé à l'aide de la méthode Node.cloneNode().

- -

Et parce que nous ajoutons son contenu à un Shadow DOM, on peut inclure des informations de mise en forme à l'intérieur de l'élément <template> dans d'un élément <style>, qui est ensuite encapsulé à l'intérieur de l'élément personnalisé. Cette procédure n'aurait pas fonctionné si on avait ajouté le contenu à un DOM standard.

- -

Par exemple :

- -
-<template id="my-paragraph">
-  <style>
-    p {
-      color: white;
-      background-color: #666;
-      padding: 5px;
-    }
-  </style>
-  <p>My paragraph</p>
-</template>
-
- -

On peut maintenent utiliser le modèle dans le document HTML:

- -
-<my-paragraph></my-paragraph>
-
- -
-

Note : Les modèles sont bien pris en charge par les navigateurs ; l'API Shadow DOM est pris en charge par défaut dans Firefox (à partir de la version 63), Chrome, Opera, Safari et Edge (à partir de la version 70).

-
- -

Plus de flexibilité avec les slots

- -

Jusque-là, nous avons vu une première utilisation de l'élément <template>. Cette implémentation n'est pas très flexible ; elle ne permet d'afficher que du texte, c'est-à-dire qu'il est aussi utile qu'un paragraphe classique ! Il est possible d'insérer du texte dans chaque instance d'élément de façon déclarative grâce à <slot>. Cette fonction est moins bien prise en charge que <template>, disponible sur Chrome 53, Opera 40, Safari 10, Firefox 59 et Edge 79.

- -

Les emplacements (slots) sont identifiés par leur attribut name, et permettent de définir des emplacements dans le modèle qui peuvent être alimentés avec n'importe quelle structure HTML.

- -

Donc, si on souhaite ajouter un emplacement dans le précédent exemple, on peut modifier l'élément de cette façon :

- -
-<p><slot name="my-text">Texte par défaut</slot></p>
-
- -

Si le contenu de l'emplacement n'est pas défini quand l'élément est inclus dans la page, ou si les emplacements ne sont pas pris en charge par le navigateur, <my-paragraph> contiendra simplement le texte statique précisé dans le modèle.

- -

Pour définir le contenu de l'emplacement, on insère une structure HTML dans <my-paragraph> avec un attribut slot dont la valeur est égale au nom de l'emplacement que l'on veut alimenter. Comme précédemment, on peut utiliser n'importe quelle structure HTML, par exemple :

- -
-<my-paragraph>
-  <span slot="my-text">Voici un autre texte&nbsp;!</span>
-</my-paragraph>
-
- -

ou

- -
-<my-paragraph>
-  <ul slot="my-text">
-    <li>Voici un autre texte&nbsp;!</li>
-    <li>dans une liste!</li>
-  </ul>
-</my-paragraph>
-
- -
-

Note : Un élément <slot> sans nom sera rempli avec l'ensemble des nœuds-fils de plus haut niveau de l'élément personnalisé qui n'ont pas d'attribut slot. Cela inclut les nœuds texte.

-
- -

Et c'est tout pour ce premier exemple. Si vous souhaitez manipuler les emplacements, vous pouvez voir la page sur GitHub (voir aussi le résultat).

- -

Un exemple plus complexe

- -

Pour finir, voyons un exemple un peu moins trivial.

- -

L'ensemble de fragments de code qui suit illustre comment utiliser <slot> avec <template> et un peu de JavaScript afin de :

- - - -

Il est techniquement possible d'utiliser un élément <slot> sans élément <template> (par exemple au sein d'un <div> classique) tout en tirant parti des fonctionnalités d'emplacement fournies par <slot> pour le contenu du Shadow DOM. On peut ainsi éviter d'avoir à d'abord accéder à la propriété content du modèle (et de la cloner). Toutefois, il est souvent plus pratique d'ajouter des emplacements au sein d'un élément <template>, car il est peu probable de définir un composant à partir d'un élément déjà rendu.

- -

De plus, même si l'élément n'est pas déjà rendu, le rôle de conteneur porté par le modèle sera sémantiquement plus clair en utilisant <template>. De plus, <template> peut avoir des éléments qui lui sont directement rattachés comme <td>. Ce même élément disparaîtrait s'il était ajouté à un élément <div>.

- -
-

Note : Vous pourrez retrouver l'exemple complet sur le dépôt GitHub pour element-details (voir également le résultat en action).

-
- -

Créer un modèle avec des emplacements

- -

Tout d'abord, on utilise l'élément <slot> au sein d'un élément <template> afin de créer notre nouveau fragment de document "element-details-template" qui contient quelques emplacements nommés :

- -
-<template id="element-details-template">
-  <style>
-  details {font-family: "Open Sans Light",Helvetica,Arial}
-  .name {font-weight: bold; color: #217ac0; font-size: 120%}
-  h4 { margin: 10px 0 -8px 0; }
-  h4 span { background: #217ac0; padding: 2px 6px 2px 6px }
-  h4 span { border: 1px solid #cee9f9; border-radius: 4px }
-  h4 span { color: white }
-  .attributes { margin-left: 22px; font-size: 90% }
-  .attributes p { margin-left: 16px; font-style: italic }
-  </style>
-  <details>
-    <summary>
-      <span>
-        <code class="name">&lt;<slot name="element-name">BESOIN D'UN NOM</slot>&gt;</code>
-        <i class="desc"><slot name="description">BESOIN D'UNE DESCRIPTION</slot></i>
-      </span>
-    </summary>
-    <div class="attributes">
-      <h4><span>Attributs</span></h4>
-      <slot name="attributes"><p>Aucun</p></slot>
-    </div>
-  </details>
-  <hr>
-</template>
-
- -

Voyons les caractéristiques de cet élément <template> :

- - - -

Créer un nouvel élément element-details avec le modèle

- -

Ensuite, voyons comment créer un nouvel élément personnalisé, intitulé <element-details>, et comment utiliser Element.attachShadow pour lui rattacher, comme racine virtuelle, le fragment de document créé avec l'élément <template> ci-dessus. Pour cela, on utilisera la même méthode qu'avec notre exemple plus simple.

- -
-customElements.define('element-details',
-  class extends HTMLElement {
-    constructor() {
-      super();
-      const template = document
-        .getElementById('element-details-template')
-        .content;
-      const shadowRoot = this.attachShadow({mode: 'open'})
-        .appendChild(template.cloneNode(true));
-    }
-  }
-);
-
- -

Utiliser l'élément element-details avec les emplacements nommés

- -

Prenons maintenant un élément <element-details> et utilisons le dans notre document :

- -
-<element-details>
-  <span slot="element-name">slot</span>
-  <span slot="description">Un emplacement dans un
-    composant web que les utilisateurs pourront remplir
-    avec leur propre contenu pour composer plusieurs
-    arbres DOM ensemble.</span>
-  <dl slot="attributes">
-    <dt>name</dt>
-    <dd>Le nom de l'emplacement.</dd>
-  </dl>
-</element-details>
-
-<element-details>
-  <span slot="element-name">template</span>
-  <span slot="description">Un mécanisme pour stocker
-    du contenu côté client qui n'est pas affiché lorsque la
-    page est chargée mais lors de l'exécution avec du code
-    JavaScript.</span>
-</element-details>
-
- -

En voyant ce fragment, notons quelques points :

- - - -

Mettre le tout en forme

- -

Pour finir, ajoutons un peu de CSS pour les éléments <dl>, <dt> et <dd> de notre document :

- -
-dl { margin-left: 6px; }
-dt { font-weight: bold; color: #217ac0; font-size: 110% }
-dt { font-family: Consolas, "Liberation Mono", Courier }
-dd { margin-left: 16px }
-
- - - -

Résultat

- -

Assemblons l'ensemble des fragments pour voir le résultat final.

- -

{{ EmbedLiveSample('exemple_complet', '300','400','element-details.png','') }}

- -

Quelques notes à propos du résultat affiché :

- - - - -
Exemple complet
- -
<!DOCTYPE html>
-<html>
-  <head>
-    <title>slot example</title>
-    <style>
-
-      dl { margin-left: 6px; }
-      dt { font-weight: bold; color: #217ac0; font-size: 110% }
-      dt { font-family: Consolas, "Liberation Mono", Courier }
-      dd { margin-left: 16px }
-
-    </style>
-  </head>
-  <body>
-    <template id="element-details-template">
-      <style>
-      details {font-family: "Open Sans Light",Helvetica,Arial}
-      .name {font-weight: bold; color: #217ac0; font-size: 120%}
-      h4 { margin: 10px 0 -8px 0; }
-      h4 span { background: #217ac0; padding: 2px 6px 2px 6px }
-      h4 span { border: 1px solid #cee9f9; border-radius: 4px }
-      h4 span { color: white }
-      .attributes { margin-left: 22px; font-size: 90% }
-      .attributes p { margin-left: 16px; font-style: italic }
-      </style>
-      <details>
-        <summary>
-          <span>
-            <code class="name">&lt;<slot name="element-name">BESOIN D'UN NOM</slot>&gt;</code>
-            <i class="desc"><slot name="description">BESOIN D'UNE DESCRIPTION</slot></i>
-          </span>
-        </summary>
-        <div class="attributes">
-          <h4><span>Attributs</span></h4>
-          <slot name="attributes"><p>Aucun</p></slot>
-        </div>
-      </details>
-      <hr>
-    </template>
-
-    <element-details>
-      <span slot="element-name">slot</span>
-      <span slot="description">Un emplacement dans un
-        composant web que les utilisateurs pourront remplir
-        avec leur propre contenu pour composer plusieurs
-        arbres DOM ensemble.</span>
-      <dl slot="attributes">
-        <dt>name</dt>
-        <dd>Le nom de l'emplacement.</dd>
-      </dl>
-    </element-details>
-
-    <element-details>
-      <span slot="element-name">template</span>
-      <span slot="description">Un mécanisme pour stocker
-        du contenu côté client qui n'est pas affiché lorsque la
-        page est chargée mais lors de l'exécution avec du code
-        JavaScript.</span>
-    </element-details>
-
-    <script>
-    customElements.define('element-details',
-      class extends HTMLElement {
-        constructor() {
-          super();
-          const template = document
-            .getElementById('element-details-template')
-            .content;
-          const shadowRoot = this.attachShadow({mode: 'open'})
-            .appendChild(template.cloneNode(true));
-        }
-      })
-    </script>
-  </body>
-</html>
- diff --git a/files/fr/web/web_components/using_templates_and_slots/index.md b/files/fr/web/web_components/using_templates_and_slots/index.md new file mode 100644 index 0000000000..60a1052b93 --- /dev/null +++ b/files/fr/web/web_components/using_templates_and_slots/index.md @@ -0,0 +1,343 @@ +--- +title: Utiliser les éléments template et slot +slug: Web/Web_Components/Using_templates_and_slots +translation_of: Web/Web_Components/Using_templates_and_slots +original_slug: Web/Web_Components/Utilisation_des_templates_et_des_slots +--- +
{{DefaultAPISidebar("Web Components")}}
+ +

Cet article explique comment utiliser les éléments <template> et <slot> pour créer un modèle (template) flexible qui peut ensuite être utilisé pour alimenter le Shadow DOM d'un composant web.

+ +

La vérité sur les modèmes

+ +

Lorsqu'une structure de balises se répète sur une page web, il est judicieux d'utiliser un modèle plutôt que d'écrire cette même structure encore et encore. Il était déjà possible de le faire, mais l'élément HTML <template> (pris en charge par les navigateurs modernes) nous facilite la tâche. Cet élément et ce qu'il renferme n'est pas directement retranscrit dans le DOM, mais peut par contre toujours être manipulé avec JavaScript.

+ +

Voyons un exemple simple :

+ +
+<template id="my-paragraph">
+  <p>My paragraph</p>
+</template>
+
+ +

Ceci restera invisible sur la page tant qu'aucune référence n'y sera faite dans le code JavaScript puis ajouté au DOM, en utilisant par exemple :

+ +
+let template = document.getElementById('my-paragraph');
+let templateContent = template.content;
+document.body.appendChild(templateContent);
+
+ +

Quoique trivial, cet exemple vous permet d'entrevoir l'interêt d'utiliser des modèles.

+ +

Accorder modèles et composants web

+ +

Les modèles sont utiles en eux-mêmes, mais ils fonctionnent encore mieux avec des composants web. Créons un composant web qui utilise notre modèle comme contenu de son Shadow DOM. Nous l'appellerons <my-paragraph> :

+ +
+customElements.define('my-paragraph',
+  class extends HTMLElement {
+    constructor() {
+      super();
+      let template = document.getElementById('my-paragraph');
+      let templateContent = template.content;
+
+      const shadowRoot = this.attachShadow({mode: 'open'})
+        .appendChild(templateContent.cloneNode(true));
+  }
+})
+ +

Le point important à noter est que l'on ajoute un clone du contenu du modèle à la racine du DOM, créé à l'aide de la méthode Node.cloneNode().

+ +

Et parce que nous ajoutons son contenu à un Shadow DOM, on peut inclure des informations de mise en forme à l'intérieur de l'élément <template> dans d'un élément <style>, qui est ensuite encapsulé à l'intérieur de l'élément personnalisé. Cette procédure n'aurait pas fonctionné si on avait ajouté le contenu à un DOM standard.

+ +

Par exemple :

+ +
+<template id="my-paragraph">
+  <style>
+    p {
+      color: white;
+      background-color: #666;
+      padding: 5px;
+    }
+  </style>
+  <p>My paragraph</p>
+</template>
+
+ +

On peut maintenent utiliser le modèle dans le document HTML:

+ +
+<my-paragraph></my-paragraph>
+
+ +
+

Note : Les modèles sont bien pris en charge par les navigateurs ; l'API Shadow DOM est pris en charge par défaut dans Firefox (à partir de la version 63), Chrome, Opera, Safari et Edge (à partir de la version 70).

+
+ +

Plus de flexibilité avec les slots

+ +

Jusque-là, nous avons vu une première utilisation de l'élément <template>. Cette implémentation n'est pas très flexible ; elle ne permet d'afficher que du texte, c'est-à-dire qu'il est aussi utile qu'un paragraphe classique ! Il est possible d'insérer du texte dans chaque instance d'élément de façon déclarative grâce à <slot>. Cette fonction est moins bien prise en charge que <template>, disponible sur Chrome 53, Opera 40, Safari 10, Firefox 59 et Edge 79.

+ +

Les emplacements (slots) sont identifiés par leur attribut name, et permettent de définir des emplacements dans le modèle qui peuvent être alimentés avec n'importe quelle structure HTML.

+ +

Donc, si on souhaite ajouter un emplacement dans le précédent exemple, on peut modifier l'élément de cette façon :

+ +
+<p><slot name="my-text">Texte par défaut</slot></p>
+
+ +

Si le contenu de l'emplacement n'est pas défini quand l'élément est inclus dans la page, ou si les emplacements ne sont pas pris en charge par le navigateur, <my-paragraph> contiendra simplement le texte statique précisé dans le modèle.

+ +

Pour définir le contenu de l'emplacement, on insère une structure HTML dans <my-paragraph> avec un attribut slot dont la valeur est égale au nom de l'emplacement que l'on veut alimenter. Comme précédemment, on peut utiliser n'importe quelle structure HTML, par exemple :

+ +
+<my-paragraph>
+  <span slot="my-text">Voici un autre texte&nbsp;!</span>
+</my-paragraph>
+
+ +

ou

+ +
+<my-paragraph>
+  <ul slot="my-text">
+    <li>Voici un autre texte&nbsp;!</li>
+    <li>dans une liste!</li>
+  </ul>
+</my-paragraph>
+
+ +
+

Note : Un élément <slot> sans nom sera rempli avec l'ensemble des nœuds-fils de plus haut niveau de l'élément personnalisé qui n'ont pas d'attribut slot. Cela inclut les nœuds texte.

+
+ +

Et c'est tout pour ce premier exemple. Si vous souhaitez manipuler les emplacements, vous pouvez voir la page sur GitHub (voir aussi le résultat).

+ +

Un exemple plus complexe

+ +

Pour finir, voyons un exemple un peu moins trivial.

+ +

L'ensemble de fragments de code qui suit illustre comment utiliser <slot> avec <template> et un peu de JavaScript afin de :

+ + + +

Il est techniquement possible d'utiliser un élément <slot> sans élément <template> (par exemple au sein d'un <div> classique) tout en tirant parti des fonctionnalités d'emplacement fournies par <slot> pour le contenu du Shadow DOM. On peut ainsi éviter d'avoir à d'abord accéder à la propriété content du modèle (et de la cloner). Toutefois, il est souvent plus pratique d'ajouter des emplacements au sein d'un élément <template>, car il est peu probable de définir un composant à partir d'un élément déjà rendu.

+ +

De plus, même si l'élément n'est pas déjà rendu, le rôle de conteneur porté par le modèle sera sémantiquement plus clair en utilisant <template>. De plus, <template> peut avoir des éléments qui lui sont directement rattachés comme <td>. Ce même élément disparaîtrait s'il était ajouté à un élément <div>.

+ +
+

Note : Vous pourrez retrouver l'exemple complet sur le dépôt GitHub pour element-details (voir également le résultat en action).

+
+ +

Créer un modèle avec des emplacements

+ +

Tout d'abord, on utilise l'élément <slot> au sein d'un élément <template> afin de créer notre nouveau fragment de document "element-details-template" qui contient quelques emplacements nommés :

+ +
+<template id="element-details-template">
+  <style>
+  details {font-family: "Open Sans Light",Helvetica,Arial}
+  .name {font-weight: bold; color: #217ac0; font-size: 120%}
+  h4 { margin: 10px 0 -8px 0; }
+  h4 span { background: #217ac0; padding: 2px 6px 2px 6px }
+  h4 span { border: 1px solid #cee9f9; border-radius: 4px }
+  h4 span { color: white }
+  .attributes { margin-left: 22px; font-size: 90% }
+  .attributes p { margin-left: 16px; font-style: italic }
+  </style>
+  <details>
+    <summary>
+      <span>
+        <code class="name">&lt;<slot name="element-name">BESOIN D'UN NOM</slot>&gt;</code>
+        <i class="desc"><slot name="description">BESOIN D'UNE DESCRIPTION</slot></i>
+      </span>
+    </summary>
+    <div class="attributes">
+      <h4><span>Attributs</span></h4>
+      <slot name="attributes"><p>Aucun</p></slot>
+    </div>
+  </details>
+  <hr>
+</template>
+
+ +

Voyons les caractéristiques de cet élément <template> :

+ + + +

Créer un nouvel élément element-details avec le modèle

+ +

Ensuite, voyons comment créer un nouvel élément personnalisé, intitulé <element-details>, et comment utiliser Element.attachShadow pour lui rattacher, comme racine virtuelle, le fragment de document créé avec l'élément <template> ci-dessus. Pour cela, on utilisera la même méthode qu'avec notre exemple plus simple.

+ +
+customElements.define('element-details',
+  class extends HTMLElement {
+    constructor() {
+      super();
+      const template = document
+        .getElementById('element-details-template')
+        .content;
+      const shadowRoot = this.attachShadow({mode: 'open'})
+        .appendChild(template.cloneNode(true));
+    }
+  }
+);
+
+ +

Utiliser l'élément element-details avec les emplacements nommés

+ +

Prenons maintenant un élément <element-details> et utilisons le dans notre document :

+ +
+<element-details>
+  <span slot="element-name">slot</span>
+  <span slot="description">Un emplacement dans un
+    composant web que les utilisateurs pourront remplir
+    avec leur propre contenu pour composer plusieurs
+    arbres DOM ensemble.</span>
+  <dl slot="attributes">
+    <dt>name</dt>
+    <dd>Le nom de l'emplacement.</dd>
+  </dl>
+</element-details>
+
+<element-details>
+  <span slot="element-name">template</span>
+  <span slot="description">Un mécanisme pour stocker
+    du contenu côté client qui n'est pas affiché lorsque la
+    page est chargée mais lors de l'exécution avec du code
+    JavaScript.</span>
+</element-details>
+
+ +

En voyant ce fragment, notons quelques points :

+ + + +

Mettre le tout en forme

+ +

Pour finir, ajoutons un peu de CSS pour les éléments <dl>, <dt> et <dd> de notre document :

+ +
+dl { margin-left: 6px; }
+dt { font-weight: bold; color: #217ac0; font-size: 110% }
+dt { font-family: Consolas, "Liberation Mono", Courier }
+dd { margin-left: 16px }
+
+ + + +

Résultat

+ +

Assemblons l'ensemble des fragments pour voir le résultat final.

+ +

{{ EmbedLiveSample('exemple_complet', '300','400','element-details.png','') }}

+ +

Quelques notes à propos du résultat affiché :

+ + + + +
Exemple complet
+ +
<!DOCTYPE html>
+<html>
+  <head>
+    <title>slot example</title>
+    <style>
+
+      dl { margin-left: 6px; }
+      dt { font-weight: bold; color: #217ac0; font-size: 110% }
+      dt { font-family: Consolas, "Liberation Mono", Courier }
+      dd { margin-left: 16px }
+
+    </style>
+  </head>
+  <body>
+    <template id="element-details-template">
+      <style>
+      details {font-family: "Open Sans Light",Helvetica,Arial}
+      .name {font-weight: bold; color: #217ac0; font-size: 120%}
+      h4 { margin: 10px 0 -8px 0; }
+      h4 span { background: #217ac0; padding: 2px 6px 2px 6px }
+      h4 span { border: 1px solid #cee9f9; border-radius: 4px }
+      h4 span { color: white }
+      .attributes { margin-left: 22px; font-size: 90% }
+      .attributes p { margin-left: 16px; font-style: italic }
+      </style>
+      <details>
+        <summary>
+          <span>
+            <code class="name">&lt;<slot name="element-name">BESOIN D'UN NOM</slot>&gt;</code>
+            <i class="desc"><slot name="description">BESOIN D'UNE DESCRIPTION</slot></i>
+          </span>
+        </summary>
+        <div class="attributes">
+          <h4><span>Attributs</span></h4>
+          <slot name="attributes"><p>Aucun</p></slot>
+        </div>
+      </details>
+      <hr>
+    </template>
+
+    <element-details>
+      <span slot="element-name">slot</span>
+      <span slot="description">Un emplacement dans un
+        composant web que les utilisateurs pourront remplir
+        avec leur propre contenu pour composer plusieurs
+        arbres DOM ensemble.</span>
+      <dl slot="attributes">
+        <dt>name</dt>
+        <dd>Le nom de l'emplacement.</dd>
+      </dl>
+    </element-details>
+
+    <element-details>
+      <span slot="element-name">template</span>
+      <span slot="description">Un mécanisme pour stocker
+        du contenu côté client qui n'est pas affiché lorsque la
+        page est chargée mais lors de l'exécution avec du code
+        JavaScript.</span>
+    </element-details>
+
+    <script>
+    customElements.define('element-details',
+      class extends HTMLElement {
+        constructor() {
+          super();
+          const template = document
+            .getElementById('element-details-template')
+            .content;
+          const shadowRoot = this.attachShadow({mode: 'open'})
+            .appendChild(template.cloneNode(true));
+        }
+      })
+    </script>
+  </body>
+</html>
+ -- cgit v1.2.3-54-g00ecf