CKTIS / JavaScript
URLSearchParams — parâmetros de consulta
URLSearchParams lê e altera parâmetros de consulta, preservando nomes repetidos e tratando a codificação em estilo de formulário.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
new URLSearchParams()
new URLSearchParams(init)
params.get(name)
params.getAll(name)
params.append(name, value)
params.set(name, value)
params.toString()URLSearchParams é uma API da norma WHATWG URL, não de ECMAScript. O construtor aceita uma consulta (opcionalmente iniciada por ?), um registo ou pares nome-valor; não analisa um URL completo.
get() devolve o primeiro valor ou null; getAll() devolve todos os valores. append() acrescenta um par. Se o nome indicado já existir, set() altera o valor do primeiro par com esse nome e remove os restantes pares com o mesmo nome. Caso contrário, set() acrescenta um novo par no fim.
toString() omite ? e utiliza application/x-www-form-urlencoded: os espaços passam a + e os sinais de mais literais passam a %2B. Passa valores não codificados aos métodos.
Alterar url.searchParams atualiza o URL associado e pode alterar a sua codificação. A norma não é uma tabela de compatibilidade dos navegadores; Node 24 não comprova o suporte nos navegadores.
Exemplos
const params = new URLSearchParams("tag=js&tag=web");
console.log(params.getAll("tag").join(","));
params.set("tag", "api");
params.append("q", "a+b c");
console.log(params.toString());Resultado
js,web tag=api&q=a%2Bb+c
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.