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

CKTIS / JavaScript

ShadowRoot.append — ajouter des nœuds et du texte à un arbre fantôme

ShadowRoot.append ajoute des nœuds et du texte à la fin d’un arbre fantôme. Cette méthode est héritée de DocumentFragment et ne constitue pas une implémentation distincte. Découvrez le déplacement des nœuds, la vidange des fragments et la différence avec appendChild().

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

shadowRoot.append(...nodesOrStrings);
fragment.append(...nodesOrStrings);

ShadowRoot.append est la méthode DocumentFragment.append héritée : ShadowRoot hérite de DocumentFragment. L’appel root.append(...) ajoute du contenu après le dernier enfant de la racine fantôme, et non aux enfants ordinaires de l’élément hôte. Un fragment ordinaire sert plutôt à assembler un sous-arbre avant de l’insérer à sa destination.

La méthode accepte plusieurs nœuds et chaînes de caractères, dans l’ordre des arguments. Les chaînes deviennent des nœuds Text ; elles ne sont pas analysées comme du HTML. Un nœud existant est déplacé, et non copié. En passant un DocumentFragment ordinaire, ses enfants sont déplacés et le fragment reste vide ; le fragment lui-même ne devient pas un enfant de la racine.

Le résultat est undefined. Contrairement à append(), appendChild() accepte un seul nœud, ne prend pas directement en charge les chaînes comme arguments et renvoie le nœud ajouté ou le fragment vidé. Une insertion invalide, par exemple si elle crée un cycle, peut déclencher une DOMException HierarchyRequestError.

Il s’agit d’une API DOM, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. MDN indique que DocumentFragment.append() est largement disponible dans les navigateurs depuis avril 2018 ; son utilisation sur une racine fantôme nécessite également la prise en charge de Shadow DOM. La présence de Node 24 dans un dépôt ne suffit pas à établir la prise en charge de ces API de navigateur.

Exemples

(() => {
  const host = document.createElement("div");
  const root = host.attachShadow({ mode: "open" });
  const fragment = document.createDocumentFragment();
  const label = document.createElement("strong");
  label.textContent = "DOM";

  fragment.append("Hello ", label);
  const result = root.append(fragment, "!");

  console.log(root.textContent);
  console.log(root.childNodes.length);
  console.log(fragment.childNodes.length);
  console.log(label.parentNode === root);
  console.log(host.childNodes.length);
  console.log(result === undefined);
})();

Résultat

Hello DOM!
3
0
true
0
true

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