Codifique ou decodifique entidades HTML _

Como funciona a codificação de entidades HTML

Uma entidade HTML é uma referência de caractere que o navegador interpreta de volta como um único caractere. Os cinco caracteres HTML reservados (<, >, &, ", ') sempre precisam ser codificados quando o texto é renderizado como HTML; os demais são opcionais e dependem da codificação do documento.

1. Escolha um modo e escopo. O modo Codificar percorre a entrada caractere por caractere. O modo Decodificar percorre a entrada em busca de padrões de entidades. O alternador de escopo decide se apenas os cinco caracteres HTML reservados são codificados ou se cada ponto de código não-ASCII também é reescrito.
2. Escolha um estilo de entidade. Entidades nomeadas (©) ficam legíveis no código-fonte. Referências decimais (©) e hexadecimais (©) cobrem todos os pontos de código Unicode sem precisar de nome. Clientes de e-mail mais antigos e parsers XML preferem as formas numéricas.
3. Percorra a entrada. Na codificação, lemos cada ponto de código e o buscamos em uma tabela interna de cerca de 200 entidades nomeadas comuns. As não encontradas recorrem ao formato numérico. Na decodificação, fazemos uma varredura com uma única regex que reconhece &nome;, &#NNN; e &#xHH; em uma só passagem.
4. Mapeie para caracteres. Correspondências nomeadas são resolvidas por uma tabela reversa. Correspondências numéricas passam por String.fromCodePoint com base 10 ou base 16. Entidades nomeadas desconhecidas são deixadas intactas para que entradas parciais sejam preservadas sem perda.
5. Modo ao vivo. Ative o modo ao vivo e cada tecla pressionada reexecuta a conversão com um debounce de 150 ms. Útil quando você está ajustando um trecho de código e quer feedback imediato antes de colá-lo em um template.

Por que codificar entidades HTML

• Evite que a entrada do usuário quebre o layout. Quando um usuário digita um < avulso em um campo de comentário, inserir esse texto diretamente no HTML reescreve o restante da página. Codificar os caracteres reservados primeiro faz o navegador renderizar o caractere em vez de interpretá-lo como início de uma tag.
• Mantenha os valores de atributos válidos. Inserir uma string entre aspas dentro de um atributo HTML requer a substituição das aspas internas por " (para atributos entre aspas duplas) ou ' (para aspas simples). Caso contrário, o parser fecha o atributo prematuramente e o restante da linha vira marcação solta.
• Neutralize HTML acidental em dados armazenados. Logs, relatórios de bugs e exportações de chat frequentemente contêm colchetes angulares e ampersands reais. Codificar o conteúdo como entidades antes de colá-lo em uma página de documentação mantém o texto visível em vez de acionar o renderizador ou o detector de links.
• Compartilhe trechos de código com segurança. Publicar uma tag como <script>alert(1)</script> em um post de blog, e-mail ou mensagem de Slack exige que os colchetes estejam codificados para o trecho ser exibido em vez de executado. A mesma técnica se aplica a corpos de feed RSS e campos `description` de JSON-LD.

Aplicações comuns

A codificação de entidades aparece sempre que texto puro é composto em HTML em tempo de execução — mesmo quando o framework normalmente cuida disso por você, a ferramenta manual é útil nos momentos em que ele não cuida.

• Templates renderizados no servidor: Jinja2, ERB, Twig e Handlebars fazem auto-escape por padrão, mas blocos raw e marcadores `safe` desligam isso — o codec permite confirmar o que o escape teria produzido.
• Criação de e-mails e newsletters: muitos mecanismos de template de ESP não fazem auto-escape em campos de mesclagem, então aspas tipográficas e símbolos de copyright em nomes fornecidos pelo usuário precisam de pré-codificação.
• Documentação e exemplos de código: colar uma tag HTML de exemplo em um post de blog em Markdown ou em um trecho de site estático requer que os colchetes estejam codificados para o renderizador tratá-los como texto visível.

Um exemplo prático

Cole <script>alert('hi')</script> na entrada com o modo Codificar, estilo Nomeado e escopo Mínimo. A saída será <script>alert('hi')</script>. Mude o estilo para Hexadecimal numérico e a mesma entrada produz <script>alert('hi')</script>. Mude o modo para Decodificar, cole a string codificada e a tag original retorna intacta.

FAQ

O que são entidades HTML?

Entidades HTML são referências de caracteres que o navegador substitui por um único caractere ao analisar a página. Existem três formas: nomeadas (como & para &), numéricas decimais (&) e numéricas hexadecimais (&). Os cinco caracteres HTML reservados (<, >, &, ", ') precisam de codificação sempre que o texto for inserido em HTML. As demais cerca de 2.225 entidades nomeadas cobrem símbolos, acentos e letras gregas, mas são opcionais quando a codificação do documento é UTF-8.

Quando devo usar entidades nomeadas ou numéricas?

Use entidades nomeadas quando quiser que o código-fonte seja legível (um revisor que vê © em um template entende imediatamente). Use as numéricas (decimal ou hexadecimal) quando o consumidor for mais antigo ou mais restrito — parsers XML, clientes de e-mail legados e alguns leitores de feed reconhecem apenas um subconjunto pequeno das entidades nomeadas do HTML5, mas todos reconhecem as formas numéricas. O formato hexadecimal tende a prevalecer em contextos voltados para segurança porque se alinha diretamente com a notação de ponto de código Unicode usada nos documentos de especificação.

A decodificação suporta entidades hexadecimais como &?

Sim. O decodificador usa uma única regex que reconhece as três formas de entidade em uma só passagem: &nome;, &#NNN; e &#xHH;. Correspondências numéricas são resolvidas com String.fromCodePoint em base 10 ou base 16. Entradas mistas (nomeadas e numéricas na mesma string) são decodificadas corretamente, e nomes desconhecidos são mantidos como texto literal para que entradas parciais sejam preservadas sem perda.

É seguro usar com entradas não confiáveis?

O codec em si roda apenas no navegador e não envia sua entrada a lugar nenhum. Se a saída é segura para incorporar depende do contexto. A codificação de entidades trata contextos de corpo HTML e de valor de atributo, que cobrem o Caso da Regra #1 do OWASP. Contextos JavaScript (handlers de eventos inline, blocos `<script>`), contextos CSS e contextos de URL exigem suas próprias regras de codificação — a codificação de entidades isolada não é suficiente nesses casos. Para uma defesa em profundidade no servidor, combine esta ferramenta com um mecanismo de template sensível ao contexto como o DOMPurify ou o auto-escape do seu framework.

A codificação de entidades no navegador fica na fronteira entre a entrada do usuário e o HTML renderizado. Fazer a conversão localmente significa que você pode verificar o que seu framework teria emitido, sem jamais enviar o texto original a uma ferramenta de terceiros.