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

CKTIS / JavaScript

HTMLElement.innerHTML: ler e substituir o conteúdo de um elemento

A leitura de `innerHTML` devolve o conteúdo do elemento como marcação. A atribuição substitui esse conteúdo por novos nós criados pelo analisador, mesmo com `+=`.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const markup = element.innerHTML;
element.innerHTML = value; // string or TrustedHTML; null is treated as ""

HTMLElement.innerHTML é uma propriedade de instância herdada de Element, não um método estático. A leitura devolve o conteúdo atual do DOM como uma cadeia de caracteres, sem as etiquetas do próprio elemento nem as raízes do Shadow DOM. É uma serialização da árvore, não uma cópia do texto de origem.

A atribuição analisa a marcação no contexto do elemento e substitui os seus nós filhos, não o próprio elemento. Em template, substitui o conteúdo de template.content. O setter aceita uma cadeia de caracteres ou TrustedHTML. A Web IDL converte null na cadeia vazia ("") antes da verificação de Trusted Types. Se a cadeia chegar inalterada ao analisador, o conteúdo é limpo. No entanto, quando são exigidos Trusted Types, uma política predefinida pode transformar a cadeia vazia em marcação não vazia, pelo que uma atribuição bem-sucedida não limpa necessariamente o conteúdo. O setter não cria raízes declarativas do Shadow DOM.

element.innerHTML += markup lê a marcação serializada, concatena o texto novo e volta a analisar todo o resultado. Os nós antigos são desligados da árvore e os ouvintes de eventos registados diretamente nesses nós não passam para os novos. Para manter os nós existentes, acrescenta os novos com append().

Não passes dados não fiáveis diretamente a innerHTML: por omissão não os higieniza e os atributos de tratamento de eventos podem dar origem a XSS, mesmo que os elementos script inseridos não sejam executados. Usa textContent para texto simples e uma ferramenta de higienização comprovada se precisares de HTML. Uma política de Trusted Types não garante, por si só, a higienização.

Esta API faz parte da plataforma web, não de ECMAScript 2024. O suporte de Trusted Types depende do ambiente. Se a CSP exigir Trusted Types e não existir uma política predefinida, atribuir uma cadeia de caracteres lança TypeError. O analisador de HTML recupera de erros de sintaxe, mas num documento XML um fragmento malformado pode lançar SyntaxError na atribuição, e um conteúdo que não possa ser serializado como XML bem formado pode lançar InvalidStateError na leitura.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>innerHTML example</title>
</head>
<body>
  <script>
    const box = document.createElement("div");
    box.innerHTML = "<strong>Hello</strong>";
    const original = box.firstElementChild;

    box.innerHTML += "<em> again</em>";

    console.log(box.innerHTML);
    console.log(box.textContent);
    console.log(original === box.firstElementChild);
    console.log(original.parentNode === null);
  </script>
</body>
</html>

Resultado

<strong>Hello</strong><em> again</em>
Hello again
false
true

Guarda o exemplo como ficheiro HTML, abre-o num navegador sem exigir Trusted Types e consulta a consola de desenvolvimento. As duas primeiras linhas comparam a marcação com o texto; as duas últimas mostram que o primeiro nó foi substituído e já não tem nó pai.

Lições relacionadas

  • JavaScript · Lição 31 · Avançado · Versão: 4

Fontes