A consulta é um componente da URL
A query string é a parte de consulta de uma URL, usada com frequência para transportar filtros, termos de busca ou parâmetros de paginação. Ela aparece depois do sinal ? e termina no início do fragmento, marcado por #, quando ele existe. O caminho e a consulta são componentes distintos do endereço.
Na URL https://example.com/produtos?pagina=2&ordem=preco, o caminho é /produtos. A consulta contém os pares pagina=2 e ordem=preco, separados por &. A aplicação pode interpretá-los como segunda página ordenada por preço, mas esses nomes não têm uma função universal definida pelo padrão de URLs.
Como preservar os valores dos parâmetros
A interface URLSearchParams manipula pares de nome e valor usando a codificação de formulários. Isso permite incluir um caractere como & no valor sem confundi-lo com o separador entre parâmetros. O padrão WHATWG define essa interpretação.
O exemplo abaixo monta uma consulta com JavaScript, sem fazer uma requisição de rede:
const url = new URL('https://example.com/busca')url.searchParams.set('q', 'café & pão')console.log(url.search)console.log(url.searchParams.get('q'))A primeira saída é ?q=caf%C3%A9+%26+p%C3%A3o. Os espaços foram representados por + e o caractere & do valor foi codificado como %26. A segunda saída recupera café & pão, confirmando que a expressão permaneceu dentro de um único parâmetro.
Você precisa comparar o valor interpretado ao investigar diferenças na URL. A propriedade search inclui o sinal de interrogação e pode usar uma representação diferente daquela produzida por searchParams. Uma alteração nos parâmetros pode reescrever a consulta, inclusive substituir %20 por + para representar espaços, como explica a documentação de URL.search.
Dúvidas frequentes
Perguntas frequentes sobre query string
- A query string pertence ao caminho da URL?
- O caminho e a consulta são componentes separados. Em /produtos?pagina=2, o caminho é /produtos e a consulta contém pagina=2.
- Toda query string precisa usar nome=valor?
- A consulta é um componente da URL e não exige esse formato em todos os usos. Pares de nome e valor separados por & são a convenção interpretada por URLSearchParams.
- Por que um espaço pode aparecer como + ou %20?
- A interface URLSearchParams usa a codificação de formulários e representa espaços com +. A propriedade search de URL pode representar o mesmo espaço como %20, por isso o texto serializado pode mudar sem alterar o valor interpretado.
Para continuar
Recursos relacionados
Documentação
MDN: consulta de uma URL
Explica como a propriedade search representa a consulta e como sua codificação difere de searchParams.
Abrir recursoSite de referência
DevSide: desenvolvimento colaborativo
Sessão técnica ao vivo para você revisar parâmetros de URLs e investigar sua interpretação pela aplicação.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao desenvolver filtros e buscas, você precisa montar os parâmetros da URL e conferir os valores que a aplicação recebe.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.