Sobre a codificação de URL
URLs só podem conter um conjunto limitado de caracteres ASCII. Caracteres especiais como espaços, e comerciais e letras não-ASCII precisam ser codificados em porcentagem — substituídos por um sinal de porcentagem seguido de dois dígitos hexadecimais representando o valor em bytes do caractere. Por exemplo, um espaço vira %20 e a letra a-trema vira %C3%A4.
Esta ferramenta usa encodeURIComponent, que codifica tudo exceto letras, dígitos e os caracteres - _ . ! ~ * ( ). É a função correta para codificar o valor de um parâmetro de query string ou um segmento de caminho, não uma URL inteira.
Como codificar em porcentagem um componente de URL?
Para codificar em porcentagem um texto para uso em uma URL, substitua todo caractere fora do conjunto não reservado (letras, dígitos e - _ . ! ~ * ' ( )) por um sinal de porcentagem seguido de dois dígitos hexadecimais representando o valor em byte UTF-8 desse caractere. Exemplo: "hello world" vira "hello%20world" e "café" vira "caf%C3%A9".
Passos para codificar e decodificar em porcentagem um componente de URL
- Converta o texto de entrada em bytes UTF-8, já que caracteres não-ASCII podem ser representados por mais de um byte.
- Examine cada byte; se corresponder a um caractere não reservado (A-Z, a-z, 0-9, - _ . ! ~ * ' ( )), deixe-o inalterado.
- Para todo outro byte, substitua-o por um sinal de porcentagem seguido de seu valor hexadecimal maiúsculo de dois dígitos, por exemplo um espaço (0x20) vira %20.
- Junte os resultados de volta em uma única string; essa é a representação codificada em porcentagem e segura para URL do texto original.
- Para decodificar, procure por % seguido de dois dígitos hex, converta cada um de volta ao seu valor de byte e remonte os bytes UTF-8 no texto original.
Regra de codificação em porcentagem
Byte reservado/inseguro -> %XX, onde XX é o valor do byte em dois dígitos hexadecimais maiúsculos
- Caracteres não reservados = A-Z, a-z, 0-9, - _ . ! ~ * ' ( ) — nunca codificados
- %XX = sinal de porcentagem mais dois dígitos hex representando um byte da codificação UTF-8 do caractere original
Exemplos de resultados de codificação
| Texto | Codificado |
|---|
| hello world | hello%20world |
| a=b&c=d | a%3Db%26c%3Dd |
| café | caf%C3%A9 |
| 100% off! | 100%25%20off! |
| user@example.com | user%40example.com |
Perguntas frequentes
Por que encodeURIComponent deixa ! ~ * ' ( ) sem escape?
Esses caracteres, junto com letras, dígitos e - _ ., são definidos como seguros para aparecer diretamente em um componente de URI e não têm significado especial ali, então o encodeURIComponent do JavaScript os deixa como estão. Outras funções como encodeURI reservam um conjunto diferente e maior de caracteres porque se destinam a codificar uma URL inteira, e não um único componente.
Qual é a diferença entre codificar um componente de URL e uma URL inteira?
Codificar um único componente (como o valor de um parâmetro de query) deve fazer escape de caracteres como & e = para que não sejam confundidos com a estrutura da URL. Codificar uma URL inteira precisa deixar caracteres estruturais como :, /, ? e & intactos para que a URL ainda seja interpretada corretamente, por isso encodeURIComponent e encodeURI se comportam de forma diferente.
Por que um espaço às vezes vira %20 e às vezes +?
%20 é a codificação em porcentagem geral para um espaço, usada no caminho da URL e na saída de encodeURIComponent. O sinal + para espaço é uma convenção legada específica do formato application/x-www-form-urlencoded usado em envios de formulários HTML e query strings, não uma regra geral de codificação de URL.
Por que a decodificação falha com erro em alguns casos?
A decodificação falha quando um % não é seguido por dois dígitos hexadecimais válidos, ou quando os bytes decodificados não formam UTF-8 válido — por exemplo, colar uma sequência de porcentagem incompleta como %E2%9 sem o byte final. Verifique se a entrada é um texto completo e corretamente codificado em porcentagem.
Esta ferramenta codifica e decodifica um único valor de texto usando o encodeURIComponent/decodeURIComponent do JavaScript, seguindo os caracteres não reservados da RFC 3986; ela não interpreta nem valida a estrutura completa de uma URL (esquema, host, caminho, query) como componentes separados.
Sources: RFC 3986 — Uniform Resource Identifier (URI): Generic Syntax