Codificador e Decodificador de URL

Uma URL possui caracteres com funções estruturais e um conjunto de caracteres que pode aparecer diretamente. Quando outro byte precisa ser representado, usa-se o sinal de porcentagem seguido por dois dígitos hexadecimais. O espaço ASCII tem valor hexadecimal 20 e, por isso, aparece como %20.

Caracteres do português são tratados como UTF-8 antes da conversão. A letra ç, por exemplo, ocupa os bytes hexadecimais C3 e A7 e vira %C3%A7. A palavra ação passa a conter várias sequências percentuais, mas volta ao original quando os bytes são decodificados corretamente.

Use a codificação de componente quando o texto será colocado dentro de um parâmetro, trecho de caminho ou valor de busca. Imagine a URL https://exemplo.com/busca?q=.... Se a consulta for café & pão, o & comercial não pode permanecer solto, pois seria interpretado como o início de outro parâmetro.

Nesse caso, encodeURIComponent produz um valor seguro e codifica símbolos como &, =, ? e #. O servidor consegue separar a estrutura da URL e depois recuperar exatamente o valor enviado pelo usuário.

Ao trabalhar com um endereço inteiro, é necessário preservar os símbolos que indicam protocolo, caminho, consulta e fragmento. encodeURI mantém caracteres como dois-pontos, barras, interrogação e cerquilha, enquanto converte espaços, acentos e outros caracteres incompatíveis.

Por exemplo, uma URL completa com a pasta São Paulo precisa codificar o espaço e o ã, mas não deve transformar todas as barras em dados comuns. Se você aplicar a codificação de componente ao endereço inteiro, ele continuará sendo texto válido, porém perderá a estrutura necessária para funcionar diretamente como link.

Antes de codificar, descubra se a entrada já contém sequências como %20 ou %C3%A7. Codificar o mesmo valor duas vezes transforma o sinal % em %25. Assim, %20 vira %2520, e uma única decodificação recupera apenas a camada anterior, não o espaço final.

1. Comece preferencialmente com o texto original.
2. Escolha componente ou URL completa conforme o contexto.
3. Codifique exatamente uma vez na fronteira onde o valor entra na URL.
4. Decodifique exatamente uma vez ao ler esse valor.

Também evite montar consultas por concatenação quando uma API oferece URL e URLSearchParams, pois essas classes reduzem erros com separadores e parâmetros repetidos.