PT
RU
EN
ES
ZH
FR
DE
AR
HI
Introdução: Por que a codificação de URL não é teoria chata, mas sim a salvação da sua aplicação
Imagine a situação: você está escrevendo uma aplicação web em JavaScript, o usuário insere uma consulta de pesquisa "JavaScript & Node.js: melhores práticas". Você passa esse texto na URL como um parâmetro de requisição GET. Abre o console do navegador — e lá está um erro. Ou, pior ainda, — a requisição é enviada, mas o servidor não a entende, e em vez de resultados de pesquisa, o usuário vê uma página vazia.
Familiar? Se sim — este artigo é para você. Se não — ainda assim é para você, porque mais cedo ou mais tarde você vai se deparar com isso. O tópico de codificação de URL em JavaScript é uma das perguntas mais populares no Stack Overflow (dezenas de milhares de visualizações), e não é à toa. É aquele pequeno detalhe que diferencia um desenvolvedor profissional de um iniciante.
Hoje vamos abordar três maneiras de codificar URLs em JavaScript, aprender a escolher a ferramenta certa para cada tarefa e ver exemplos reais da vida de um desenvolvedor web. Vamos lá!
O que é codificação de URL e por que ela é necessária
Antes de escrever código, vamos entender a teoria. Uma URL (Uniform Resource Locator) tem uma estrutura rigorosa. Apenas certos caracteres são permitidos: letras latinas, dígitos e alguns caracteres especiais (-, _, ., ~). Já espaços, cirílico, caracteres como &, ?, # e outros — são proibidos.
Quando tentamos passar esses caracteres em uma URL, o navegador ou servidor pode interpretar a requisição incorretamente. Por exemplo, o caractere & na string de consulta separa os parâmetros uns dos outros. Se ele aparecer dentro do valor de um parâmetro — a lógica quebra.
A solução — codificação de URL (codificação percentual). Caracteres proibidos são substituídos por uma sequência do tipo %XX, onde XX é o código hexadecimal do caractere na codificação UTF-8. Por exemplo, o espaço se torna %20, e o "а" cirílico se torna %D0%B0.
Em JavaScript, existem três mecanismos embutidos para isso. Vamos analisar cada um.
Maneira 1: encodeURI() — para URLs completas
A função encodeURI() é projetada para codificar uma URL completa. Ela substitui todos os caracteres, exceto aqueles que fazem parte da sintaxe do URI: :, /, ?, #, &, = e outros.
Sintaxe
encodeURI(uri)Exemplo
const url = "https://pythonlib.ru/search?q=JavaScript & Node.js";
const encoded = encodeURI(url);
console.log(encoded);
// Resultado: "https://pythonlib.ru/search?q=JavaScript%20&%20Node.js"
Observe: encodeURI() codificou os espaços, mas não tocou nos caracteres &, ? e =. Isso é correto para uma URL completa, mas perigoso para parâmetros. Se em nossa consulta houvesse um caractere & dentro do valor do parâmetro, ele teria permanecido como está e quebrado a string de consulta.
Quando usar
- Quando precisar codificar uma URL inteira (por exemplo, para passar para
window.location) - Quando a URL não contém dados do usuário com caracteres potencialmente perigosos
Quando NÃO usar
- Para codificar parâmetros de consulta individuais
- Se a URL contiver entrada do usuário (formulários, pesquisa, comentários)
Maneira 2: encodeURIComponent() — para parâmetros e valores
Esta é sua principal ferramenta do dia a dia. encodeURIComponent() codifica todos os caracteres, exceto letras, dígitos e -, _, ., ~. Ela codificará até mesmo os caracteres que fazem parte da sintaxe do URI — &, ?, =, # e assim por diante.
