Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Element.attachShadow — attacher un arbre Shadow DOM

Element.attachShadow() attache une racine Shadow DOM à un élément compatible et renvoie un ShadowRoot. Le mode requis, open ou closed, contrôle l’accès via host.shadowRoot, mais ne constitue pas une frontière de sécurité.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

const root = element.attachShadow({ mode: "open" });

Element.attachShadow() crée un arbre Shadow DOM associé à un élément hôte et renvoie son ShadowRoot. Il s’agit d’un arbre séparé : ses nœuds ne deviennent pas des enfants ordinaires de l’hôte. Par conséquent, host.querySelector() ne recherche pas à l’intérieur ; appelez plutôt la méthode sur la racine renvoyée.

L’option mode est obligatoire. Avec "open", host.shadowRoot expose la racine ; avec "closed", elle renvoie null. Dans les deux modes, attachShadow() renvoie la racine : une référence conservée permet donc toujours de la modifier. "closed" ne protège pas les données confidentielles.

Tous les éléments ne peuvent pas servir d’hôtes : div est compatible, mais input, par exemple, ne l’est pas. Un hôte non compatible ou une nouvelle attache à une racine ordinaire déjà existante provoque NotSupportedError. Une racine déclarative existante constitue une exception : un mode identique permet de la réutiliser, mais efface son contenu ; un mode différent provoque une erreur.

Il s’agit d’une API DOM de navigateur, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. Vérifiez typeof Element.prototype.attachShadow === "function" dans le navigateur cible ; ce test ne garantit pas la prise en charge de toutes les options supplémentaires. La présence de Node 24 dans le dépôt ne prouve pas la prise en charge de cette API.

Exemples

(() => {
  const host = document.createElement("div");
  const root = host.attachShadow({ mode: "open" });
  const label = document.createElement("span");
  label.textContent = "Hello";
  root.append(label);

  console.log(host.shadowRoot === root);
  console.log(host.querySelector("span") === null);
  console.log(root.querySelector("span").textContent);
})();

Résultat

true
true
Hello

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources