Codificação e decodificação de URL, explicadas para desenvolvedores
Digite um espaço em uma URL, ou uma palavra em cirílico, ou um e-comercial que pertence aos seus dados e não ao endereço em si, e algo precisa ceder. A web só garante transporte seguro para um conjunto pequeno e previsível de caracteres ASCII. Todo o resto precisa ser embrulhado em um formato com o qual roteadores, servidores e navegadores concordem. Esse formato é a codificação por porcentagem, mais comumente chamada de codificação de URL, e esta página permite que você converta texto em qualquer direção diretamente no seu navegador.
O que é, de fato, a codificação por porcentagem
A regra é mecânica e fácil de seguir. Qualquer caractere que não possa aparecer literalmente é substituído por um sinal % seguido de dois dígitos hexadecimais que soletram o valor de byte daquele caractere. Um espaço vira %20. Um sinal de mais vira %2B. O sinal de cerquilha vira %23. Quando um caractere corresponde a vários bytes, como acontece com a maioria do texto não-ASCII em UTF-8, você simplesmente obtém vários trios em sequência: o símbolo do euro vira %E2%82%AC. A decodificação reverte o processo, lendo cada trio de volta no seu byte original.
Essa convenção está definida na especificação de URI (RFC 3986) e é deliberadamente entediante. O tédio é o objetivo. Todo cliente e servidor HTTP bem-comportado do planeta implementa as mesmas regras, então um link corretamente codificado em um lugar chega intacto em qualquer outro.
Por que ela precisa existir
As URLs carregam dois tipos de caracteres com funções muito diferentes. Os caracteres reservados, como /, ?, #, &, = e :, são estruturais. Eles dizem a um parser onde o caminho termina e a query string começa, ou onde um parâmetro para e o próximo começa. Se os seus dados de fato contiverem um desses símbolos, ele precisa ser codificado para que o parser não o confunda com pontuação. Uma referência de pedido como A&B/2024 jogada crua em uma query string seria interpretada erroneamente como dois parâmetros e um segmento de caminho.
Depois há os caracteres inseguros e não-ASCII: espaços, aspas, sinais de maior e menor, letras acentuadas, emoji, qualquer coisa fora da faixa ASCII simples. Eles não têm por que aparecer literalmente em uma URL, seja porque são deturpados no trajeto, seja porque não têm representação definida. Codificá-los mantém os links limpos e previsíveis, em vez de deixar o resultado à sorte.
Onde ela aparece no trabalho real
As query strings são o caso clássico. Todo valor que você anexa a ?key=... deve ser codificado para que a entrada do usuário não possa quebrar a estrutura. O mesmo vale para envios de formulários HTML enviados como application/x-www-form-urlencoded, em que o navegador codifica os valores dos campos automaticamente (e, por convenção histórica, transforma espaços em + em vez de %20). Você também a encontra ao construir links que apontam para páginas com títulos não latinos, ao montar requisições de API na mão, ao passar destinos de redirecionamento como parâmetros e ao depurar por que uma requisição que parece correta na barra de endereços chega embaralhada ao servidor.
encodeURI em comparação com encodeURIComponent
O JavaScript traz dois codificadores, e escolher o errado é um bug comum. A diferença é de escopo. O encodeURIComponent é para um único pedaço de dado, como um valor de query. Ele codifica quase tudo, incluindo os caracteres reservados /, ?, :, @, &, =, + e #. É exatamente o que você quer quando o dado pode conter esses símbolos como texto comum.
O encodeURI é para um endereço inteiro que você pretende manter funcionando. Ele deixa os caracteres estruturais em paz, então as barras, dois-pontos e pontos de interrogação que mantêm a URL coesa sobrevivem. Use-o quando você tiver uma URL completa e só quiser limpar espaços ou caracteres não-ASCII; recorra ao encodeURIComponent sempre que estiver inserindo um valor dentro de uma URL maior. Uma regra prática simples: codifique o link inteiro com encodeURI, codifique as partes que você encaixa nele com encodeURIComponent.
Tudo permanece na sua máquina
Esta ferramenta roda inteiramente no seu navegador. O texto que você cola é codificado ou decodificado localmente com as mesmas rotinas padrão e nunca viaja para um servidor, o que a torna segura para tokens, parâmetros assinados ou qualquer outra coisa que você prefira não enviar pela rede. Se você trabalha com outras transformações de texto, o conversor Base64 fica logo ao lado, e você pode navegar pelo conjunto completo de ferramentas para desenvolvedores para encontrar mais ajudantes do dia a dia.
Perguntas frequentes
O que significa %20 em uma URL?
É um espaço codificado. O caractere de espaço não é permitido literalmente em uma URL, então ele é substituído por um sinal de porcentagem e o valor hexadecimal 20, que é o valor de byte de um espaço.
Por que às vezes vejo um sinal de mais em vez de %20?
Os dados de formulário HTML do tipo application/x-www-form-urlencoded codificam espaços como um sinal de mais por convenção histórica. Em um caminho ou query normal, um espaço é codificado como %20. Ambos decodificam de volta para um espaço no contexto adequado.
Quando devo usar encodeURIComponent em vez de encodeURI?
Use encodeURIComponent para um único valor que você está inserindo em uma URL, como um parâmetro de query, porque ele também codifica os caracteres reservados. Use encodeURI para um endereço completo quando quiser preservar as barras, dois-pontos e pontos de interrogação que o mantêm coeso.
A codificação de URL muda o significado dos meus dados?
Não. A codificação é totalmente reversível. Decodificar o resultado devolve exatamente o texto original, byte por byte, desde que o mesmo conjunto de caracteres seja usado nas duas pontas.
Como caracteres não-ASCII, como acentos ou emoji, são tratados?
Eles são primeiro transformados em bytes UTF-8 e então cada byte vira o seu próprio trio de porcentagem. Uma única letra acentuada ou emoji pode, portanto, expandir-se em vários trios na saída codificada.
Meu texto é enviado a um servidor quando uso esta ferramenta?
Não. A codificação e a decodificação acontecem inteiramente no seu navegador. Nada do que você cola é enviado, então é seguro usar com strings privadas ou sensíveis.