diff options
Diffstat (limited to 'files')
| -rw-r--r-- | files/fr/web/web_components/using_shadow_dom/index.html | 118 |
1 files changed, 57 insertions, 61 deletions
diff --git a/files/fr/web/web_components/using_shadow_dom/index.html b/files/fr/web/web_components/using_shadow_dom/index.html index 2b534f8358..12170a6e71 100644 --- a/files/fr/web/web_components/using_shadow_dom/index.html +++ b/files/fr/web/web_components/using_shadow_dom/index.html @@ -13,13 +13,14 @@ translation_of: Web/Web_Components/Using_shadow_DOM <p class="summary">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.</p> -<div class="note"> -<p><strong>Note</strong>: 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.</p> +<div class="notecard note"> + <p><b>Note :</b></p> + <p>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.</p> </div> -<h2 id="Vue_de_haut_niveau">Vue de haut niveau</h2> +<h2 id="high-level_view">Vue de haut niveau</h2> -<p>Cet article suppose que vous êtes déjà familier avec le concept de <a href="/en-US/docs/Web/API/Document_Object_Model/Introduction">DOM (Document Object Model)</a> — 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 :</p> +<p>Cet article suppose que vous êtes déjà familier avec le concept de <a href="/fr/docs/Web/API/Document_Object_Model/Introduction">DOM (Document Object Model)</a> — 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 :</p> <pre class="brush: html"><!DOCTYPE html> <html> @@ -28,64 +29,65 @@ translation_of: Web/Web_Components/Using_shadow_DOM <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> + <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></pre> <p>Ce fragment produit la structure DOM suivante :</p> -<p><img alt="" src="https://mdn.mozillademos.org/files/14559/dom-screenshot.png" style="border-style: solid; border-width: 1px; display: block; margin: 0px auto;"></p> +<p><img src="dom-screenshot.png"></p> <p>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.</p> -<p><img alt="" src="https://mdn.mozillademos.org/files/15788/shadow-dom.png" style="height: 543px; width: 1138px;"></p> +<p><img alt="Version SVG du diagramme montrant l'interaction entre le document, la racine fantôme et l'hôte fantôme." src="shadowdom.svg"></p> <p>Il y a quelques termes de la terminologie du DOM fantôme que vous devez connaitre :</p> <ul> - <li><strong>Hôte fantôme </strong>: le nœud du DOM principal auquel le DOM fantôme est associé.</li> - <li><strong>Arbre fantôme</strong>: l'arbre DOM au sein du DOM fantôme.</li> - <li><strong>Frontière fantôme</strong>: la limite où le DOM fantôme se termine et où le DOM principal commence.</li> - <li><strong>Racine fantôme</strong>: le nœud racine de l'arbre fantôme.</li> + <li><strong>Hôte fantôme </strong>: le nœud du DOM principal auquel le DOM fantôme est associé.</li> + <li><strong>Arbre fantôme</strong>: l'arbre DOM au sein du DOM fantôme.</li> + <li><strong>Frontière fantôme</strong>: la limite où le DOM fantôme se termine et où le DOM principal commence.</li> + <li><strong>Racine fantôme</strong>: le nœud racine de l'arbre fantôme.</li> </ul> -<p>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 atributs, en stylisant des nœuds individuels au moyen de <code>element.style.propriete</code>, ou en ajoutant du style à l'arbre DOM fantôme entier via une balise {{htmlelement("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.</p> +<p>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 <code>element.style.propriete</code>, ou en ajoutant du style à l'arbre DOM fantôme entier via une balise <a href="/fr/docs/Web/HTML/Element/style"><code><style></code></a>. 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.</p> -<p>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 {{htmlelement("video")}}, avec les contrôles par défaut du navigateur apparents. Tout ce que vous voyez dans le DOM est l'élément <code><video></code>, 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.</p> +<p>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 <a href="/fr/docs/Web/HTML/Element/video"><code><video></code></a>, avec les contrôles par défaut du navigateur apparents. Tout ce que vous voyez dans le DOM est l'élément <code><video></code>, 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.</p> -<h2 id="Usage_basique">Usage basique</h2> +<h2 id="basic_usage">Usage basique</h2> -<p>Vous pouvez associer une racine fantôme à tout élément en utilisant la méthode {{domxref("Element.attachShadow()")}}. Elle prend en paramètres un objet d'options contenant une option — <code>mode</code> — ayant pour valeur <code>open</code> (ouvert) ou <code>closed</code> (fermé) :</p> +<p>Vous pouvez associer une racine fantôme à tout élément en utilisant la méthode <a href="/fr/docs/Web/API/Element/attachShadow"><code>Element.attachShadow()</code></a>. Elle prend en paramètres un objet d'options contenant une option — <code>mode</code> — ayant pour valeur <code>open</code> (ouvert) ou <code>closed</code> (fermé) :</p> <pre class="brush: js">let fantome = element.attachShadow({mode: 'open'}); let fantome = element.attachShadow({mode: 'closed'});</pre> -<p><code>open</code> 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é {{domxref("Element.shadowRoot")}} :</p> +<p><code>open</code> 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é <a href="/fr/docs/Web/API/ShadowRoot"><code>Element.shadowRoot</code></a> :</p> <pre class="brush: js">let monDomFantome = monElementPerso.shadowRoot;</pre> -<p>Si vous associez une racine fantôme à un élément personnalisé avec la propriété <code>mode</code> définie à <code>closed</code>, vous ne serez pas autorisé à acéder au DOM fantôme depuis l'extérieur — <code>monElementPerso.shadowRoot</code> retournera <code>null</code>. C'est le casavec les éléments natifs contenant des DOM fantômes tels que <code><video></code>.</p> +<p>Si vous associez une racine fantôme à un élément personnalisé avec la propriété <code>mode</code> définie à <code>closed</code>, vous ne serez pas autorisé à accéder au DOM fantôme depuis l'extérieur — <code>monElementPerso.shadowRoot</code> retournera <code>null</code>. C'est le casavec les éléments natifs contenant des DOM fantômes tels que <code><video></code>.</p> -<div class="note"> -<p><strong>Note</strong>: Comme montre <a href="https://blog.revillweb.com/open-vs-closed-shadow-dom-9f3d7427d1af">cet article de blog</a>, 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.</p> +<div class="notecard note"> + <p><b>Note :</b></p> + <p>Comme montre <a href="https://blog.revillweb.com/open-vs-closed-shadow-dom-9f3d7427d1af">cet article de blog</a> <small>(en anglais)</small>, 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.</p> </div> <p>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 :</p> -<pre class="brush: js">let fantome = this.attachShadow({mode: 'open'});</pre> +<pre class="brush: js">let shadow = this.attachShadow({mode: 'open'});</pre> <p>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 :</p> -<pre class="brush: js">let paragraphe = document.createElement('p'); -fantome.appendChild(paragraphe); +<pre class="brush: js">let paragraph = document.createElement('p'); +shadow.appendChild(paragraph); // etc.</pre> -<h2 id="Démonstration_au_travers_dun_exemple_simple">Démonstration au travers d'un exemple simple</h2> +<h2 id="working_through_a_simple_example">Démonstration au travers d'un exemple simple</h2> -<p>Maintenant, visitons un exemple simple pour faire une démonstration du DOM fantôme en action au sein d'un élément personnalisé — <code><a href="https://github.com/mdn/web-components-examples/tree/master/popup-info-box-web-component"><popup-info-box></a></code> (en voir aussi un <a href="https://mdn.github.io/web-components-examples/popup-info-box-web-component/">exemple dynamique</a>). Il prend un icône et une chaine de caractères et intègre l'image dans la page. Quand l'icône obtient l'attention (<code>:focus</code>), 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 <code>PopUpInfo</code>, qui étend <code>HTMLElement</code>:</p> +<p>Maintenant, visitons un exemple simple pour faire une démonstration du DOM fantôme en action au sein d'un élément personnalisé — <code><a href="https://github.com/mdn/web-components-examples/tree/master/popup-info-box-web-component"><popup-info-box></a></code> (en voir aussi un <a href="https://mdn.github.io/web-components-examples/popup-info-box-web-component/">exemple dynamique</a>). 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 (<code>:focus</code>), 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 <code>PopUpInfo</code>, qui étend <code>HTMLElement</code>:</p> <pre class="brush: js">class PopUpInfo extends HTMLElement { constructor() { @@ -100,48 +102,47 @@ fantome.appendChild(paragraphe); <p>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.</p> -<h3 id="Créer_la_racine_fantôme">Créer la racine fantôme</h3> +<h3 id="creating_the_shadow_root">Créer la racine fantôme</h3> -<p>Nous associns d'abord une racine fantôme à l'élément personnalisé :</p> +<p>Nous associons d'abord une racine fantôme à l'élément personnalisé :</p> <pre class="brush: js">// Créer une racine fantome var fantome = this.attachShadow({mode: 'open'});</pre> -<h3 class="brush: js" id="Créer_la_structure_du_DOM_fantôme">Créer la structure du DOM fantôme</h3> +<h3 id="creating_the_shadow_dom_structure">Créer la structure du DOM fantôme</h3> <p class="brush: js">Ensuite, nous utilisons des outils de manipulation du DOM pour créer la structure interne du DOM fantôme de notre élément:</p> <pre class="brush: js">// Créer les <span> -var wrapper = document.createElement('span'); +let wrapper = document.createElement('span'); wrapper.setAttribute('class','wrapper'); -var icon = document.createElement('span'); +let icon = document.createElement('span'); icon.setAttribute('class','icon'); icon.setAttribute('tabindex', 0); -var info = document.createElement('span'); +let info = document.createElement('span'); info.setAttribute('class','info'); -// Take attribute content and put it inside the info span -var text = this.getAttribute('text'); +// Prendre le contenu de l'attribut et le placer à l'intérieur du span info +let text = this.getAttribute('text'); info.textContent = text; -// Insert icon -var imgUrl; +// Insérer l'icône +let imgUrl; if(this.hasAttribute('img')) { imgUrl = this.getAttribute('img'); } else { imgUrl = 'img/default.png'; } -var img = document.createElement('img'); +let img = document.createElement('img'); img.src = imgUrl; -icon.appendChild(img); -</pre> +icon.appendChild(img);</pre> -<h3 class="brush: js" id="Styliser_le_DOM_fantôme">Styliser le DOM fantôme</h3> +<h3 id="styling_the_shadow_dom">Styliser le DOM fantôme</h3> -<p class="brush: js">Après celà, nous créons un élément {{htmlelement("style")}} et nous l'emplissons avec du CSS pour personnaliser notre arbre DOM :</p> +<p class="brush: js">Après cela, nous créons un élément <a href="/fr/docs/Web/HTML/Element/style"><code><style></code></a> et nous ajoutons du CSS pour personnaliser notre arbre DOM :</p> <pre class="brush: js">// Créer quelque CSS à appliquer au dom fantôme -var style = document.createElement('style'); +let style = document.createElement('style'); style.textContent = ` .wrapper { @@ -170,11 +171,9 @@ img { .icon:hover + .info, .icon:focus + .info { opacity: 1; -}`; +}`;</pre> -</pre> - -<h3 id="Associer_le_DOM_fantôme_à_la_racine_fantôme">Associer le DOM fantôme à la racine fantôme</h3> +<h3 id="attaching_the_shadow_dom_to_the_shadow_root">Associer le DOM fantôme à la racine fantôme</h3> <p>L'étape finale est d'associer tous les éléments créés à la racine fantôme :</p> @@ -184,21 +183,19 @@ shadow.appendChild(wrapper); wrapper.appendChild(icon); wrapper.appendChild(info);</pre> -<h3 id="Utiliser_notre_élément_personnalisé">Utiliser notre élément personnalisé</h3> +<h3 id="using_our_custom_element">Utiliser notre élément personnalisé</h3> -<p>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 <a href="/en-US/docs/Web/Web_Components/Using_custom_elements">Utiliser les éléments personnalisés</a> :</p> +<p>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 <a href="/fr/docs/Web/Web_Components/Using_custom_elements">Utiliser les éléments personnalisés</a> :</p> <pre class="brush: js">// Définit le nouvel élément customElements.define('popup-info', PopUpInfo);</pre> -<pre class="brush: html"><<span class="pl-ent">popup-info</span> <span class="pl-e">img</span>=<span class="pl-s"><span class="pl-pds">"</span>img/alt.png<span class="pl-pds">"</span></span> <span class="pl-e">text</span>=<span class="pl-s"><span class="pl-pds">"</span>Your card validation code (CVC) is an extra - security feature — it is the last 3 or 4 - numbers on the back of your card.<span class="pl-pds">"</span></span>></pre> +<pre class="brush: html"><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."></pre> -<div> -<h3 id="Styles_internes_ou_styles_externes">Styles internes ou styles externes</h3> +<h3 id="internal_versus_external_styles">Styles internes ou styles externes</h3> -<p>Dans l'exemple précédent, nous appliquons du style au DOM fantôme en utilisant l'élément {{htmlelement("style")}}, mais il est parfaitement possible de le faire en référençant une feuille de style externe avec un élément {{htmlelement("link")}} si vous le préférez.</p> +<p>Dans l'exemple précédent, nous appliquons du style au DOM fantôme en utilisant l'élément <a href="/fr/docs/Web/HTML/Element/style"><code><style></code></a>, mais il est parfaitement possible de le faire en référençant une feuille de style externe avec un élément <a href="/fr/docs/Web/HTML/Element/link"><code><link></code></a> si vous le préférez.</p> <p>Par exemple, regardez ce code tiré de l'exemple <a href="https://mdn.github.io/web-components-examples/popup-info-box-external-stylesheet/">popup-info-box-external-stylesheet</a> (voir le <a href="https://github.com/mdn/web-components-examples/blob/master/popup-info-box-external-stylesheet/main.js">code source</a>):</p> @@ -210,14 +207,13 @@ linkElem.setAttribute('href', 'style.css'); // Associer l'élément créé au dom fantôme shadow.appendChild(linkElem);</pre> -<p>Notez que les éléments {{htmlelement("link")}} ne bloquent pas les repeinturages 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.</p> +<p>Notez que les éléments <a href="/fr/docs/Web/HTML/Element/link"><code><link></code></a> 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.</p> -<p>De nombreux navigateurs modernes implantent une optimisation pour les balises {{htmlelement("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.</p> +<p>De nombreux navigateurs modernes implantent une optimisation pour les balises <a href="/fr/docs/Web/HTML/Element/style"><code><style></code></a> 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.</p> -<h2 id="Voir_aussi">Voir aussi</h2> +<h2 id="see_also">Voir aussi</h2> <ul> - <li><a href="/en-US/docs/Web/Web_Components/Using_custom_elements">Utiliser les éléments personnalisés</a></li> - <li><a href="/en-US/docs/Web/Web_Components/Using_templates_and_slots">Utiliser les modèles (templates) et les emplacements (slots)</a></li> + <li><a href="/fr/docs/Web/Web_Components/Using_custom_elements">Utiliser les éléments personnalisés</a></li> + <li><a href="/fr/docs/Web/Web_Components/Using_templates_and_slots">Utiliser les modèles (templates) et les emplacements (slots)</a></li> </ul> -</div> |