Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.

Fontes