É fácil escapar errado porque vários trabalhos diferentes parecem semelhantes à distância. Tem texto, o texto contém caracteres especiais e outro sistema precisa de o receber sem o compreender mal. O erro é assumir que um tipo de fuga funciona em todo o lado.
A codificação de URL, o escape de HTML e o escape de JSON resolvem problemas diferentes. Um espaço numa string de consulta não é o mesmo problema que um caractere < em HTML renderizado ou uma aspa dentro de uma string JSON. A ferramenta Case / Slug / Escape ajuda a manter estas saídas próximas umas das outras, mas a parte útil é saber qual a saída que pertence ao destino que está a preparar.
A codificação de URL é para URLs e valores de consulta
Utilize a codificação URL quando o texto é introduzido num componente URL, especialmente um parâmetro de consulta ou um valor que possa conter espaços, pontuação ou caracteres não seguros para o caminho.
Suponha que um link de suporte necessita de incluir um termo de pesquisa como pricing & billing. Colar esta frase diretamente num URL pode alterar a forma como o URL é interpretado porque & já tem significado dentro de uma string de consulta. A codificação de URL transforma o texto num formato que pode viajar dentro do URL sem ser confundido com a sintaxe do URL.
Isto é diferente de criar um slug. Um slug transforma frequentemente um título num segmento de caminho legível, como por exemplo pricing-and-billing. A codificação de URL preserva o valor original de forma mais direta para o transporte.
O escape HTML é para texto que será renderizado em HTML
Utilize o escape HTML quando o texto necessita de aparecer como texto dentro de um contexto HTML, e não se tornar uma marcação.
Se um exemplo de código incluir <button> e pretender que os leitores vejam esses caracteres, o browser necessitará que os caracteres sejam escapados. Caso contrário, poderá interpretá-los como um elemento real. O escape HTML consiste em evitar que o texto seja lido como sintaxe HTML em locais onde o conteúdo deve permanecer como texto visível.
Isto é importante na documentação, nos campos do CMS, nos registos de alterações e na cópia do produto. É especialmente relevante quando o texto de partida inclui exemplos de marcação, snippets ou valores gerados pelo utilizador que não deveriam fazer parte da estrutura da página.
O escape JSON é para valores de string dentro de JSON
Utilize o escape JSON quando o texto necessita de estar seguro dentro de uma string JSON.
As aspas são inofensivas na prosa normal, mas dentro de uma string JSON pode fechar a string antecipadamente. Uma nova linha pode também necessitar de uma representação que mantenha o JSON válido. O escape JSON consiste em preservar o valor, mantendo o JSON circundante analisável.
Isto aparece normalmente quando as equipas partilham exemplos de API, snippets de configuração, cargas analíticas ou dados de exemplo. Se o passo seguinte for uma limpeza mais ampla dos dados estruturados, combine este artigo com Como formatar JSON antes de partilhar um exemplo de API e o Conversor JSON/YAML/TOML.
Escolha o escape com base no destino
A regra mais simples é o destino primeiro.
| Destino | Uso | Porquê |
|---|---|---|
| Valor de consulta URL ou componente URL | Codificação de URL | Evita que o texto seja interpretado como sintaxe URL |
| Texto visível dentro do HTML | Escape de HTML | Evita que caracteres especiais se tornem marcações |
| Valor da string dentro do JSON | Escape JSON | Mantém citações, barras e quebras de linha analisáveis |
| Artigo público ou título da rota | Slug geração | Cria um texto de caminho legível em vez de preservar todos os caracteres |
O Converty ajuda porque pode colar uma vez e comparar as saídas sem abrir um codificador separado para cada caso. Isto mantém o trabalho proporcional. Não está a construir um pipeline; está a preparar um valor de texto para o lugar que ele precisa de ir.
Abra a ferramenta Case / Slug / Escape quando precisar de decidir se a próxima saída deve ser um slug, um valor codificado em URL, um texto seguro para HTML ou uma string segura para JSON.
