HTML Entity Encoder / Decoder

O que são entidades HTML

Entidades HTML são sequências de escape que permitem incluir caracteres reservados (<, >, &, ", ') ou caracteres especiais em documentos HTML sem que o navegador os interprete como markup. Existem em duas formas: named refs como < e &, e numeric refs como < (decimal) ou < (hexadecimal).

A especificação HTML5 define mais de 2200 entidades nomeadas — uma lista completa em html.spec.whatwg.org/multipage/named-characters.html.

Quando você precisa codificar

• Renderizar input do usuário em HTML. Se você concatena texto não escapado em uma string HTML, atacantes podem injetar tags <script>. Codificar < como < neutraliza isso.
• Exibir código em uma página. Para mostrar <div> literal em um post de blog, você precisa codificar para que o navegador renderize o texto em vez de criar uma div.
• Atributos. Aspas dentro de valores de atributo precisam virar " ou ' para não quebrar o parsing.

Quando NÃO codificar

• URLs. URLs usam percent-encoding (%3C), não entidades HTML. Use o tool URL Encode/Decode.
• JSON. JSON tem suas próprias regras de escape (\", <). Não misture.
• Strings JavaScript. Use \x3C ou < em strings JS.

Named vs numeric

<!-- Equivalentes -->
&lt;
&#60;
&#x3C;

Named refs são mais legíveis (© vs ©) mas exigem suporte do parser. Numeric refs funcionam em qualquer parser HTML válido. Para máxima compatibilidade em emails ou XML, prefira numeric.

O perigo silencioso

document.innerHTML = userInput sem escape é uma das raízes mais comuns de XSS. Mesmo quando o input parece "limpo", payloads como <img src=x onerror=alert(1)> passam. Sempre escape, ou use textContent que não interpreta HTML.

A biblioteca he usada aqui implementa o algoritmo de decode da especificação HTML5, lidando corretamente com:

• Referências sem ; final em contextos legados (&amp ainda decodifica para &)
• Pares surrogate Unicode (😀 → 😀)
• Edge cases como &CounterClockwiseContourIntegral; (sim, existe)

Decodificação

Decodificar é o caminho inverso: pegar Hello World! e produzir Hello World!. Útil quando você recebe HTML de uma API, salva texto em banco, ou faz scraping.

Cuidado: decodificar HTML que você vai re-injetar em DOM é perigoso. Decode-then-inject re-introduz a vulnerabilidade XSS que o encode evitou. Decode apenas para exibir em campos de texto, contextos non-HTML, ou para análise.

Tudo local

Toda codificação acontece no navegador via he. Nenhuma string toca nossos servidores — abra o Network tab e veja: zero requisições.

Por que < precisa virar < em HTML?

Porque o navegador interpreta < como início de uma tag. Se você quer exibir o caractere literal < na página (em um exemplo de código, por exemplo), precisa codificá-lo. Sem isso, <div> no seu texto vira uma div real.

Qual a diferença entre & e &?

Ambos representam &. A primeira é uma named reference (mais legível); a segunda é numeric (decimal). Existe também & (hexadecimal). Use named quando disponíveis para legibilidade, numeric quando precisar de máxima compatibilidade (XML, parsers antigos).

Decodificar HTML antes de inserir no DOM é seguro?

Não. Decodificar e depois fazer innerHTML = decoded reintroduz o vetor XSS que o encode preveniu. Decodifique apenas para exibir em campos de texto, processar conteúdo, ou contextos não-HTML. Para DOM, use textContent.

Por que algumas entidades não têm ; final?

HTML5 mantém compatibilidade com referências legadas: &amp (sem ;) ainda decodifica para & em certos contextos. Em código novo, sempre termine com ; — é o comportamento documentado e previsível.

Meu input passa por servidor?

Não. Tudo é processado no seu navegador pela biblioteca he. Abra o Network tab — zero requisições. Funciona offline depois do primeiro carregamento.

Como lidar com emoji e caracteres não-ASCII?

A biblioteca he suporta a referência hexadecimal completa, incluindo pares surrogate para caracteres fora do BMP. 😀 decodifica para 😀. Para encode, ative a opção "use named references when available" se quiser nomes; caso contrário, gera numeric refs.