ShadowRoot

Baseline Widely available *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis ⁨janvier 2020⁩.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

L'interface ShadowRoot, relative à l'API Shadow DOM, représente la racine d'un sous-arbre du DOM dont le rendu est effectué séparément de celui du DOM de l'arbre principal.

Il est possible de récupérer une référence à la racine shadow d'un élément via la propriété Element.shadowRoot si la racine a été créée avec la méthode Element.attachShadow() et l'option mode qui valait open.

Propriétés

ShadowRoot.delegatesFocus Lecture seule Non standard: Cette propriété renvoie un booléen qui indique si l'option delegatesFocus a été activée lors de la liaison avec la racine shadow (cf. Element.attachShadow()).
ShadowRoot.host Lecture seule: Cette propriété renvoie une référence à l'élément DOM auquel la racine ShadowRoot est attachée.
ShadowRoot.innerHTML Non standard: Cette propriété permet de définir ou de récupérer le sous-arbre DOM contenu à l'intérieur de la racine ShadowRoot.
ShadowRoot.mode Lecture seule: Cette propriété renvoie le mode utilisé pour la racine ShadowRoot : open ou closed. Cette valeur indique si les fonctionnalités internes à la racine sont accessibles depuis JavaScript.

Propriétés incluses via `DocumentOrShadowRoot`

L'interface ShadowRoot inclut les propriétés suivantes grâce au mixin DocumentOrShadowRoot. Attention, ceci n'est actuellement (11/2019) implémenté qu'avec Chrome et les autres navigateurs continuent d'implémenter l'interface Document.

DocumentOrShadowRoot.activeElement Lecture seule: L'élément (Element) au sein du sous-arbre shadow qui a le focus.
DocumentOrShadowRoot.styleSheets Lecture seule: Une liste StyleSheetList d'objets CSSStyleSheet qui référencent les feuilles de styles liées explicitement ou embarquées dans le document.

Méthodes

L'interface ShadowRoot inclut les méthodes suivantes qui proviennent du mixin DocumentOrShadowRoot. Attention, ceci n'est actuellement (11/2019) implémenté qu'avec Chrome et les autres navigateurs continuent d'implémenter l'interface Document.

DocumentOrShadowRoot.getSelection(): Cette méthode renvoie un objet Selection représentant le fragment de texte sélectionné par l'utilisateur ou la position courante du curseur.
DocumentOrShadowRoot.elementFromPoint(): Cette méthode renvoie l'élément le plus haut situé aux coordonnées passées en arguments.
DocumentOrShadowRoot.elementsFromPoint(): Cette méthode renvoie un tableau de tous les éléments situés aux coordonnées passées en arguments.
DocumentOrShadowRoot.caretPositionFromPoint(): Cette méthode renvoie un objet CaretPosition contenant le nœud DOM sur lequel est le curseur ainsi que la position du curseur sur ce nœud.

Exemples

Les fragments de code suivants sont extraits de l'exemple life-cycle-callbacks (voir le résultat en live) qui crée un élément affichant un carré avec une taille et une couleur fournies par les attributs de l'élément.

Dans la définition de la classe pour l'élément <custom-square>, on ajoute certains callbacks permettant de gérer le cycle de vie de l'élément avec un appel à une fonction externe updateStyle() qui applique la taille et la couleur à l'élément. On lui passe l'argument this (c'est-à-dire l'élément lui-même).

connectedCallback() {
  console.log("Le carré personnalisé a été ajouté à la page.");
  updateStyle(this);
}

attributeChangedCallback(nom, ancienneValeur, nouvelleValeur) {
  console.log("Les attributs du carré ont changé.");
  updateStyle(this);
}

Quant à la fonction updateStyle(), voyons ici son fonctionnement. On récupère une référence au shadow DOM avec Element.shadowRoot. Ensuite, on utilise un parcours pour le sous-arbre afin de trouver l'élément <style> présent dans le shadow DOM et on met à jour le CSS pour cet élément :

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") +
        ";" +
        "}";
    }
  }
}