URLSearchParams

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

A interface URLSearchParams define métodos utilitários para trabalhar com os parâmetros de uma URL.

Um objeto que implementa URLSearchParams pode ser usado diretamente em uma estrutura for...of para iterar sobre pares chave/valor na mesma ordem em que elas aparecem nos parâmetros, por exemplo as linhas a seguir são equivalentes:

for (const [key, value] of mySearchParams) {
}
for (const [key, value] of mySearchParams.entries()) {
}

Note: This feature is available in Web Workers.

Construtor

URLSearchParams(): Retorna uma instância do objeto URLSearchParams.

Métodos

URLSearchParams.append(): Adiciona o par chave/valor especificado como um novo parâmetro de busca.
URLSearchParams.delete(): Exclui o parâmetro de pesquisa fornecido e seu valor associado da lista de todos os parâmetros de pesquisa.
URLSearchParams.entries(): Retorna um iterator permitindo a iteração através de todos os pares de chave/valor contidos neste objeto na mesma ordem em que aparecem na string de consulta.
URLSearchParams.forEach(): Permite a iteração através de todos os valores contidos neste objeto por meio de uma função de retorno de chamada.
URLSearchParams.get(): Retorna o primeiro valor associado ao parâmetro de pesquisa fornecido.
URLSearchParams.getAll(): Retorna todos os valores associados a um determinado parâmetro de pesquisa.
URLSearchParams.has(): Retorna um valor booleano indicando se tal parâmetro existe.
URLSearchParams.keys(): Retorna um iterator permitindo a iteração através de todas as chaves dos pares chave/valor contidos neste objeto.
URLSearchParams.set(): Define o valor associado a um determinado parâmetro de pesquisa para o valor fornecido. Se houver vários valores, os demais serão excluídos.
URLSearchParams.sort(): Ordena todos os pares de chave/valor, se houver, por suas chaves.
URLSearchParams.toString(): Retorna uma string contendo uma string de consulta adequada para uso em uma URL.
URLSearchParams.values(): Retorna um iterator permitindo a iteração através de todos os valores dos pares chave/valor contidos neste objeto.

Exemplos

const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);

// Iterando os parâmetros de pesquisa
for (const p of searchParams) {
  console.log(p);
}

console.log(searchParams.has("topic")); // true
console.log(searchParams.get("topic") === "api"); // true
console.log(searchParams.getAll("topic")); // ["api"]
console.log(searchParams.get("foo") === null); // true
console.log(searchParams.append("topic", "webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=api&topic=webdev"
console.log(searchParams.set("topic", "More webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=More+webdev"
console.log(searchParams.delete("topic"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams"

// Os parâmetros de pesquisa também podem ser objetos
const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);

console.log(searchParams.toString()); // "foo=bar&baz=bar"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // "bar"

Parâmetros de pesquisa duplicados

const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar, somente o primeiro valor
console.log(searchParams.getAll("foo")); // ["bar", "baz"]

Sem análise de URL

O construtor URLSearchParams não analisa URLs completas. No entanto, ele retirará um ? inicial inicial de uma string, se presente.

const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);

console.log(searchParams1.has("query")); // false
console.log(searchParams1.has("http://example.com/search?query")); // true

console.log(searchParams1.get("query")); // null
console.log(searchParams1.get("http://example.com/search?query")); // "@" (equivalente a decodeURIComponent('%40'))

const paramsString2 = "?query=value";
const searchParams2 = new URLSearchParams(paramsString2);
console.log(searchParams2.has("query")); // true

const url = new URL("http://example.com/search?query=%40");
const searchParams3 = new URLSearchParams(url.search);
console.log(searchParams3.has("query")); // true

Preservando os sinais de adição

O construtor URLSearchParams interpreta sinais de adição (+) como espaços, o que pode causar problemas.

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' são substituídos por espaços

console.log(atob(binQuery) === rawData); // false

Você pode evitar isso codificando os dados com o encodeURIComponent().

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

Valor vazio vs. nenhum valor

URLSearchParams não distingue entre parâmetros com nada após o = e um parâmetro que não possui um =.

const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo")); // retorna ''
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo")); // também retorna ''
console.log(noEquals.toString()); // 'foo=&bar=baz'

Especificações

Specification
URL Standard # urlsearchparams

Compatibilidade com navegadores

BCD tables only load in the browser