No desenvolvimento front end, a manipulação de parâmetros de URL, como os utilizados em requisições GET, é uma tarefa frequente. A API Web URLSearchParams oferece uma maneira eficiente e conveniente para gerenciar a string de consulta de uma URL.

A URLSearchParams é uma interface nativa do JavaScript que facilita a análise e a modificação de strings de consulta de URL. Ela abstrai a complexidade de trabalhar com strings brutas, permitindo que você manipule os pares chave-valor de forma programática.

Considere a seguinte URL de exemplo:

https://example.com?nome=Joao&idade=30

A string de consulta aqui é nome=Joao&idade=30. A URLSearchParams permite que você interaja com esses parâmetros de maneira estruturada.

Inicializando URLSearchParams

Você pode criar uma instância de URLSearchParams de algumas maneiras:

1. Com uma string de consulta existente

const parametros = new URLSearchParams('nome=Joao&idade=30');

2. Com um objeto literal

const parametros = new URLSearchParams({ nome: 'Joao', idade: '30' });

3. A partir da URL da página atual

const parametros = new URLSearchParams(window.location.search);

Métodos Essenciais

Recuperando Valores de Parâmetros

• .get(chave): Retorna o valor associado à primeira ocorrência da chave especificada.
• .getAll(chave): Retorna um array com todos os valores associados à chave especifiacda. Útil para parâmetros repetidos.
• .has(chave): Retorna true se a chave existir na string de consulta, false caso contrário.

const params = new URLSearchParams('nome=Joao&idade=30&tag=frontend&tag=web');

console.log(params.get('nome'));    // Saída: 'Joao'
console.log(params.getAll('tag'));  // Saída: ['frontend', 'web']
console.log(params.has('idade'));     // Saída: true
console.log(params.get('sobrenome')); // Saída: null

Modificando Parâmetros

• .set(chave, valor): Define ou atualiza o valor de um parâmetro. Se a chave já existir, seu valor é substituído. Se não existir, é adicionada.
• .append(chave, valor): Adiciona um novo par chave-valor. Diferente de .set(), permite múltiplos valores para a mesma chave.
• .delete(chave): Remove todos os pares chave-valor associados à chave especificada.

const params = new URLSearchParams('nome=Joao&idade=30');

params.set('idade', '25');        // Atualiza 'idade' para '25'
params.append('profissao', 'Dev'); // Adiciona 'profissao=Dev'
params.append('tag', 'javascript'); // Adiciona 'tag=javascript'
params.append('tag', 'api');       // Adiciona outro 'tag=api'
params.delete('nome');          // Remove o parâmetro 'nome'

console.log(params.toString()); // Saída: 'idade=25&profissao=Dev&tag=javascript&tag=api'

Iterando sobre os Parâmetros

Você pode percorrer os parâmetros de diversas formas:

• .keys(): Retorna um iterador com todas as chaves.
• .values(): Retorna um iterador com todos os valores.
• .entries(): Retorna um iterador com pares [chave, valor].
• for...of: Permite iterar diretamente sobre os pares chave-valor.

const params = new URLSearchParams('nome=Joao&idade=30&cidade=Recife');

// Usando for...of
console.log("Iterando com for...of:");
for (const [chave, valor] of params) {
  console.log(`${chave}: ${valor}`);
  // Saída:
  // nome: Joao
  // idade: 30
  // cidade: Recife
}

// Convertendo para arrays para visualização
console.log("\nChaves:", Array.from(params.keys()));     // Saída: ['nome', 'idade', 'cidade']
console.log("Valores:", Array.from(params.values()));   // Saída: ['Joao', '30', 'Recife']
console.log("Entradas:", Array.from(params.entries())); // Saída: [['nome', 'Joao'], ['idade', '30'], ['cidade', 'Recife']]

Convertendo para String

O método .toString() é fundamental para reconstruir a string de consulta a partir do objeto.

const params = new URLSearchParams();
params.set('pagina', 1);
params.set('itensPorPagina', 20);

const queryString = params.toString();
console.log(queryString); // Saída: 'pagina=1&itensPorPagina=20'

const urlCompleta = `https://api.exemplo.com/dados?${queryString}`;
console.log(urlCompleta); // Saída: https://api.exemplo.com/dados?pagina=1&itensPorPagina=20

Exemplos Práticos

1. Extraindo Parâmetros da URL Atual

// Supondo a URL: https://meusite.com/busca?termo=javascript&filtro=avancado
const urlParams = new URLSearchParams(window.location.search);
const termoBusca = urlParams.get('termo'); // 'javascript'
const nivelFiltro = urlParams.get('filtro'); // 'avancado'

console.log(`Buscando por: ${termoBusca}, com filtro: ${nivelFiltro}`);

2. Construindo URLs Dinamicamente

function criarUrlComFiltros(baseUrl, filtros) {
  const params = new URLSearchParams();
  filtros.forEach(filtro => {
    params.append('categoria', filtro.categoria);
    params.append('valorMax', filtro.valor);
  });
  return `${baseUrl}?${params.toString()}`;
}

const urlBase = 'https://api.loja.com/produtos';
const meusFiltros = [
  { categoria: 'eletronicos', valor: 1500 },
  { categoria: 'casa', valor: 300 }
];

const urlFinal = criarUrlComFiltros(urlBase, meusFiltros);
console.log(urlFinal);
// Saída: https://api.loja.com/produtos?categoria=eletronicos&valorMax=1500&categoria=casa&valorMax=300

3. Removendo Parâmetros Específicos

const paramsPendentes = new URLSearchParams('status=pendente&usuarioId=123&status=aguardando');

// Remover todas as ocorrências de 'status'
paramsPendentes.delete('status');

console.log(paramsPendentes.toString()); // Saída: 'usuarioId=123'

Considerações Importantes

• Codificação Automática: A URLSearchParams lida automaticamente com a codificação de caracteres especiais (espaços, acentos, etc.) para garantir que a URL seja válida. Por exemplo, params.set('query', 'olá mundo') resulta em query=ol%C3%A1%20mundo.
• Sensibilidade a Maiúsculas/Minúsculas: Os nomes dos parâmetros são sensíveis a maiúsculas e minúsculas. params.get('Nome') é diferente de params.get('nome').
• Compatibilidade: É amplamente suportada por navegadores modernos. O Internet Explorer não a suporta nativamente; nesses casos, bibliotecas como qs ou implementações manuais podem ser utilizadas.

A URLSearchParams é uma ferramenta padrão e robusta para interagir com strings de consulta de URL, oferecendo uma alternativa mais confiável e fácil de usar em comparação com a manipulação manual de strings.