Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

HTMLTemplateElement: conteúdo inerte do modelo

HTMLTemplateElement armazena o conteúdo do modelo num DocumentFragment separado, acessível através de content. O conteúdo não é apresentado dentro do modelo; pode ser copiado com document.importNode() e inserido no documento sem consumir o original.

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

Sintaxe

const template = document.createElement("template");
template.content.append(document.createElement("p"));
const fragment = document.importNode(template.content, true);
document.body.append(fragment);

Conteúdo inerte do modelo é o conteúdo de um elemento template normal, guardado para utilização posterior em vez de ser apresentado no local onde é declarado. A interface HTMLTemplateElement disponibiliza esse conteúdo através de content como um DocumentFragment. Trata-se de uma API DOM do navegador, não de uma funcionalidade ECMAScript; a mera presença do Node.js 24 não comprova a sua disponibilidade.

Procure os nós do modelo através de template.content.querySelector(), não de template.querySelector(). O conteúdo analisado pertence ao fragmento, não aos filhos normais do elemento. A propriedade content é só de leitura, mas o próprio fragmento pode ser alterado. Esta inércia não é o mesmo que o atributo global inert, que restringe a interação com elementos existentes.

Utilize document.importNode(template.content, true) para copiar toda a subárvore no contexto do documento de destino. Isto é importante para criar elementos personalizados, porque o conteúdo do modelo pertence a um documento separado. Ao inserir um fragmento, os seus filhos são movidos para o destino e o fragmento fica vazio. Assim, inserir diretamente template.content consumiria o conteúdo do modelo em vez de o preservar para reutilização.

A interface principal e content estão amplamente disponíveis nos navegadores desde novembro de 2015; as funcionalidades mais recentes requerem verificações de compatibilidade próprias. O exemplo diz respeito a um modelo normal, não ao Shadow DOM declarativo: durante a análise, uma declaração adequada que utilize shadowrootmode pode criar um ShadowRoot em vez de um HTMLTemplateElement.

Exemplos

(() => {
  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();
})();

Resultado

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

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes