ShadowRoot

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

Spécifications

Spécification État Commentaires
DOM
La définition de 'Interface ShadowRoot' dans cette spécification.
Standard évolutif

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung Internet
ShadowRoot
Expérimentale
Chrome Support complet 57Edge Support complet 79Firefox Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 40Safari Support complet 10.1WebView Android Support complet 57Chrome Android Support complet 57Firefox Android Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 41Safari iOS Support complet 10.3Samsung Internet Android Support complet 6.0
delegatesFocus
Expérimentale
Chrome Support complet 57Edge Support complet 79Firefox ? IE Aucun support NonOpera ? Safari Aucun support NonWebView Android Support complet 57Chrome Android Support complet 57Firefox Android ? Opera Android ? Safari iOS Aucun support NonSamsung Internet Android Support complet 7.0
Features included from the DocumentOrShadowRoot mixin
Expérimentale
Chrome Support complet 57Edge Support complet 79Firefox Support complet 63IE Aucun support NonOpera Support complet 40Safari Aucun support Non
Notes
Aucun support Non
Notes
Notes Features still implemented on the Document interface
WebView Android Support complet 57Chrome Android Support complet 57Firefox Android Support complet 63Opera Android Support complet 41Safari iOS Aucun support Non
Notes
Aucun support Non
Notes
Notes Features still implemented on the Document interface
Samsung Internet Android Support complet 6.0
host
Expérimentale
Chrome Support complet 57Edge Support complet 79Firefox Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 40Safari Support complet 10.1WebView Android Support complet 57Chrome Android Support complet 57Firefox Android Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 41Safari iOS Support complet 10.3Samsung Internet Android Support complet 6.0
innerHTML
ExpérimentaleNon-standard
Chrome Support complet 57Edge Support complet 79Firefox Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 40Safari Support complet 10.1WebView Android Support complet 57Chrome Android Support complet 57Firefox Android Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 41Safari iOS Support complet 10.3Samsung Internet Android Support complet 6.0
mode
Expérimentale
Chrome Support complet 57Edge Support complet 79Firefox Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 40Safari Support complet 10.1WebView Android Support complet 57Chrome Android Support complet 57Firefox Android Support complet 63
Support complet 63
Aucun support 59 — 63
Désactivée
Désactivée From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 41Safari iOS Support complet 10.3Samsung Internet Android Support complet 6.0

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Fonctionnalité non-standard. Celle-ci peut être incorrectement supportée par les autres navigateurs.
Fonctionnalité non-standard. Celle-ci peut être incorrectement supportée par les autres navigateurs.
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.