Trabalhando com URLSearchParams em JavaScript

Como você já sabe, ao trabalhar com formulários e requisições GET em JavaScript, surgem strings com este formato:

let paramsString = 'a=1&b=2&c=3';

Às vezes, é necessário alterar programaticamente o valor de algum parâmetro nesta string. Escrever código que faça isso não é muito conveniente. Portanto, o JavaScript possui uma classe especial integrada URLSearchParams para trabalhar com esse tipo de string.

Vamos criar um objeto desta classe, passando como parâmetro nossa string com os parâmetros:

let paramsString = 'a=1&b=2&c=3';
let searchParams = new URLSearchParams(paramsString);

Vamos ver quais métodos o objeto criado possui.

Obtendo o valor de um parâmetro

Usando o método get, você pode obter o valor de um parâmetro:

let res = searchParams.get('a');
console.log(res);

Vamos tentar obter o valor de um parâmetro inexistente:

let res = searchParams.get('x');
console.log(res); // exibirá null

Verificando a existência de um parâmetro

Usando o método has, você pode verificar a existência de um parâmetro. Vamos verificar um parâmetro existente:

let res = searchParams.has('a');
console.log(res); // exibirá true

Vamos verificar um parâmetro inexistente:

let res = searchParams.has('x');
console.log(res); // exibirá false

Convertendo para string

Usando o método toString, você pode converter nosso objeto de volta para uma string:

let res = searchParams.toString();
console.log(res); // exibirá 'a=1&b=2&c=3'

Modificando parâmetros

Usando o método set, você pode alterar o valor de um parâmetro:

searchParams.set('b', 'x');

Vamos verificar as alterações:

let res = searchParams.toString();
console.log(res); // exibirá 'a=1&b=x&c=3'

Adicionando parâmetros

Usando o método set, você também pode adicionar um novo parâmetro:

searchParams.set('d', '4');

Vamos verificar as alterações:

let res = searchParams.toString();
console.log(res); // exibirá 'a=1&b=2&c=3&d=4'

Adicionando parâmetros

Usando o método append, você também pode adicionar um novo parâmetro:

searchParams.append('d', '4');

Vamos verificar as alterações:

let res = searchParams.toString();
console.log(res); // exibirá 'a=1&b=2&c=3&d=4'

Vamos tentar adicionar um parâmetro que já existe:

searchParams.append('a', '4');

Neste caso, o método simplesmente adicionará um parâmetro com o mesmo nome no final:

let res = searchParams.toString();
console.log(res); // exibirá 'a=1&b=2&c=3&a=4'

É aqui que reside a diferença entre os métodos set e append. O primeiro altera um parâmetro existente, enquanto o segundo simplesmente adiciona uma duplicata dele no final.

Removendo parâmetros

Usando o método delete, você pode remover parâmetros:

searchParams.delete('b');

Vamos verificar as alterações:

let res = searchParams.toString();
console.log(res); // exibirá 'a=1&c=3'

Iterando sobre os parâmetros com um loop

Você pode iterar sobre os parâmetros com um loop:

for (let p of searchParams) {
	console.log(p);
}

Vários parâmetros idênticos

Suponha que nossa string tenha vários parâmetros iguais:

let paramsString = 'a=1&a=2b=2&c=3';

Usando o método getAll, você pode obter um array com os valores desses parâmetros:

let res = searchParams.getAll('a');
console.dir(res); // exibirá [1, 2]

Tarefas práticas

Suponha a seguinte string com parâmetros:

let paramsString = 'test1=param1&test2=param2&test3=param3';

Adicione a esta string mais um parâmetro test3.

Remova desta string o parâmetro test2.

Altere o parâmetro test1 para um novo valor.