Codificar / decodificar URL

O que é a codificação de URL?#

As URLs só podem conter um pequeno conjunto de caracteres sem escape — letras ASCII, dígitos, e um punhado de símbolos como -, _, ., ~. Tudo o resto (um espaço, um &, um carácter chinês, um emoji, mesmo um / quando se destina a dado em vez de separador de caminho) tem de ser escrito como um escape codificado por percentagem: % seguido de dois dígitos hexadecimais, como %20 para um espaço ou %E4%B8%AD para os bytes UTF-8 de 中. A codificação de URL é a tradução mecânica que torna texto arbitrário seguro para viajar dentro de uma URL.

Há dois trabalhos distintos que são constantemente confundidos, e esta ferramenta expõe ambos através do seletor Opções:

• Modo Componente (o caminho encodeURIComponent do JavaScript) faz escape a tudo o que não seja uma letra, dígito, ou um de - _ . ! ~ * ' (. Use isto quando o texto é um único pedaço de dado que se vai largar num parâmetro de consulta, num segmento de caminho, ou num fragmento — para que caracteres com significado estrutural (/ ? & = #) sejam reduzidos a texto literal inofensivo.
• Modo URL completa (o caminho encodeURI) faz escape aos mesmos bytes inseguros mas deixa intocados os caracteres estruturais da própria URL (: / ? # [ ] @ ! $ & ' ( ) * + , ; =). Use isto quando tem uma URL completa que já tem a forma certa e só quer limpar os caracteres literais lá dentro.

A decodificação inverte qualquer das formas. Quando a entrada contém um escape malformado como %GG (hex inválido) ou um % solitário, a ferramenta revela o erro e aponta para a posição ofensiva em vez de adivinhar.

Como usar#

1. Escolha Codificar ou Decodificar no interruptor no canto superior esquerdo.
2. Em Opções, escolha Componente para um único valor que está colocando numa URL, ou URL completa para uma URL inteira que deve manter a sua estrutura.
3. Cole no painel Entrada à esquerda.
4. Leia o resultado no painel Saída à direita e clique em Copiar.
5. Exemplo carrega uma string de demonstração; Limpar repõe os painéis.

Principais funcionalidades#

• Dois âmbitos reais, não um. Componente versus URL completa espelha exatamente a distinção encodeURIComponent / encodeURI, pelo que pode fazer escape a um único valor ou limpar uma URL inteira sem trocar de ferramenta.
• UTF-8 por padrão. Os caracteres não-ASCII são codificados como a sua sequência de bytes UTF-8 (o padrão desde o RFC 3986), pelo que 中文 se torna %E4%B8%AD%E6%96%87, não um blob Latin-1 de escape único.
• Erros apontam para a posição. Quando a descodicação bate num escape % inválido, a linha de estado indica onde está, em vez de deitar fora toda a entrada.
• Corre localmente. Tudo acontece no seu navegador; nada do que cola é enviado.

Exemplo prático#

Codificar o fragmento a/b?c=d & e com o modo Componente produz:

a%2Fb%3Fc%3Dd%20%26%20e

Repare que / se torna %2F, ? torna-se %3F, = torna-se %3D, o espaço torna-se %20, e & torna-se %26 — todos os caracteres que poderiam de outro modo ser lidos como estrutura de URL foram neutralizados. Esta é a forma correta para enfiar a string inteira num único valor de consulta.

Agora mude para o modo URL completa e codifique uma URL completa:

https://example.com/path?q=hello world&lang=zh CN

O resultado mantém o protocolo, as barras, ? e & intactos e só faz escape aos espaços literais:

https://example.com/path?q=hello%20world&lang=zh%20CN

Essa é a diferença entre os dois modos num só relance: Componente achata tudo para dados, URL completa preserva o esqueleto da URL e só limpa os bytes que precisavam.

FAQ#

Componente ou URL completa — como decido?#

Se está construindo uma string de consulta e um dos valores veio de entrada do usuário, codifique esse valor com Componente. Se já tem uma URL totalmente formada que simplesmente contém alguns caracteres perdidos (espaços, acentos), passe o todo por URL completa. Um teste útil: a saída ainda precisa do seu ?, & e / para funcionar como ligação? Então use URL completa. Esses caracteres são afinal parte dos dados? Então use Componente.

A minha string decodificada tem %GG e a ferramenta dá erro. Porque?#

% tem de ser sempre seguido por dois dígitos hexadecimais. %GG não é hex válido, pelo que o decodificador o recusa e reporta a posição — a mesma entrada que lançaria um URIError em código. Corrija a fonte para enviar %25 (a forma codificada de um % literal) ou corrija o escape malformado.

Devo codificar antes ou depois de construir a string de consulta?#

Codifique cada valor antes de o juntar com = e &. Se construir primeiro ?q=a & b e depois codificar o todo com o modo Componente, o = e o & também são escapados e o servidor deixa de os ver como separadores. Codifique as partes e depois assemble.

Isto lida com Unicode da mesma forma que os navegadores?#

Sim. Os navegadores e servidores modernos esperam que escapes de percentagem transportem bytes UTF-8, e é o que esta ferramenta emite — 中 torna-se %E4%B8%AD. Se está depurando um sistema antigo que espera uma codificação legada de byte único (Latin-1, GBK, etc.), os bytes diferirão e precisará de uma ferramenta específica da codificação.