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.
io error: No such file or directory (os error 2) (/home/runner/work/yari/yari/mdn/translated-content/files/pt-br/web/api/url_api/index.md)
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()) {
}
Nota: 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