O que é URL Encoding (Percent-Encoding) e Quando Usar
O URL Encoding — formalmente chamado de Percent-Encoding pela especificação RFC 3986 — é o mecanismo padrão utilizado na web para representar caracteres especiais, espaços e letras acentuadas dentro de um Uniform Resource Identifier (URI). Por definição, uma URL só pode trafegar com segurança utilizando um subconjunto restrito de caracteres ASCII.
Quando um caractere fora desse conjunto seguro (como ç, ã, espaços em branco ou símbolos como & e = dentro de um valor) precisa ser enviado na barra de endereços ou em uma requisição HTTP GET, ele é convertido nos seus bytes correspondentes em UTF-8 e cada byte é escrito em hexadecimal precedido pelo sinal %.
Diferença Prática entre encodeURIComponent e encodeURI
No desenvolvimento web com JavaScript, TypeScript e Node.js, escolher a função incorreta pode quebrar links de redirecionamento ou corromper parâmetros de consulta:
1. encodeURIComponent (Recomendado para Parâmetros)
Escapa todos os delimitadores reservados (incluindo : / ? & = # +). É indispensável quando você passa um texto do usuário, um filtro de pesquisa ou uma URL de callback (redirect_uri) dentro de um parâmetro de query string.
2. encodeURI (Para URLs Completas)
Preserva a sintaxe estrutural da URL (mantém https://, barras de caminho e o ponto de interrogação) e codifica apenas espaços e caracteres não-ASCII (como caminhos com acentuação).
Tabela de Referência de Caracteres Reservados em URL
| Caractere | Código URL (UTF-8) | Papel na URL / Observação |
|---|---|---|
| (Espaço) | %20 (ou +) | Espaço em branco padrão RFC 3986 ou formulário HTML |
| & | %26 | Separador de múltiplos parâmetros na query string |
| = | %3D | Atribuição entre chave e valor do parâmetro |
| ? | %3F | Início da query string da URL |
| / | %2F | Separador de diretórios/rotas de caminho |
| : | %3A | Delimitador de protocolo (https:) e porta (:8080) |
| # | %23 | Identificador de âncora/fragmento da página |
| % | %25 | Caractere de escape percentual literal |
Perguntas Frequentes sobre URL Encode e Decode
Qual a diferença entre encodeURI e encodeURIComponent no JavaScript?
A função encodeURI foi projetada para codificar uma URL completa, preservando os delimitadores estruturais como ':', '/', '?', '&', '=' e '#'. Já a função encodeURIComponent codifica todos os caracteres especiais de pontuação e deve ser usada ao passar valores individuais dentro de parâmetros query string (por exemplo, quando um parâmetro contém outra URL ou o símbolo '&').
Por que o espaço às vezes vira %20 e às vezes vira o sinal de mais (+)?
Na especificação oficial de URIs (RFC 3986), o caractere espaço é sempre codificado como %20. Entretanto, o formato histórico de envio de formulários HTML (application/x-www-form-urlencoded) substitui espaços pelo caractere '+' nas query strings. Na ferramenta acima, você pode alternar entre os dois padrões conforme a necessidade da sua API.
O que significa o erro 'URIError: malformed URI sequence' ao decodificar?
Esse erro ocorre quando a string contém um sinal de porcentagem '%' que não é seguido por dois dígitos hexadecimais válidos (por exemplo, escrever '100%' sem codificar como '100%25') ou quando uma sequência UTF-8 de múltiplos bytes foi cortada ao meio.
As URLs e parâmetros colados aqui são enviados para algum servidor?
Não. Toda a codificação e decodificação ocorre 100% localmente no seu navegador via JavaScript nativo. Nenhum link, token ou parâmetro de API sai do seu dispositivo.
