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