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

CKTIS / JavaScript

HTMLTemplateElement : contenu inerte d’un modèle

HTMLTemplateElement stocke le contenu d’un modèle dans un DocumentFragment distinct, accessible via content. Ce contenu n’est pas affiché dans le modèle ; copiez-le avec document.importNode() et insérez-le dans le document sans consommer l’original.

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 template = document.createElement("template");
template.content.append(document.createElement("p"));
const fragment = document.importNode(template.content, true);
document.body.append(fragment);

Le contenu inerte d’un modèle désigne le contenu d’un élément template ordinaire, conservé pour une utilisation ultérieure au lieu d’être affiché à l’endroit où il est déclaré. L’interface HTMLTemplateElement expose ce contenu via content, sous la forme d’un DocumentFragment. Il s’agit d’une API DOM du navigateur, et non d’une fonctionnalité ECMAScript ; la seule présence de Node.js 24 ne garantit pas sa disponibilité.

Recherchez les nœuds du modèle avec template.content.querySelector(), et non avec template.querySelector(). Le contenu analysé appartient au fragment, et non aux enfants ordinaires de l’élément. La propriété content est en lecture seule, mais le fragment lui-même peut être modifié. Cet état inerte n’est pas la même chose que l’attribut global inert, qui limite les interactions avec les éléments existants.

Utilisez document.importNode(template.content, true) pour copier tout le sous-arbre dans le contexte du document cible. C’est important pour créer des éléments personnalisés, car le contenu d’un modèle appartient à un document distinct. L’insertion d’un fragment déplace ses enfants vers la destination et vide le fragment. Insérer directement template.content consommerait donc le contenu du modèle au lieu de le préserver pour une réutilisation.

L’interface de base et content sont largement disponibles dans les navigateurs depuis novembre 2015 ; les fonctionnalités plus récentes nécessitent des vérifications de compatibilité distinctes. L’exemple porte sur un modèle ordinaire, et non sur le Shadow DOM déclaratif : lors de l’analyse, une déclaration appropriée utilisant shadowrootmode peut créer un ShadowRoot à la place d’un HTMLTemplateElement.

Exemples

(() => {
  const template = document.createElement("template");
  const paragraph = document.createElement("p");
  paragraph.textContent = "Hello";
  template.content.append(paragraph);

  const host = document.createElement("section");
  document.body.append(host);
  console.log(`before: ${host.childElementCount}`);

  const fragment = document.importNode(template.content, true);
  fragment.querySelector("p").textContent = "Hello, template!";
  host.append(fragment);

  console.log(`rendered: ${host.textContent}`);
  console.log(`template: ${template.content.textContent}`);
  console.log(`fragment children: ${fragment.childNodes.length}`);
  host.remove();
})();

Résultat

before: 0
rendered: Hello, template!
template: Hello
fragment children: 0

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