A API URLSearchParams
fornece uma interface consistente para os bits e partes do URL e permite a manipulação trivial da string de consulta (aquela depois de ?
).
Tradicionalmente, os desenvolvedores usam regexs e divisão de strings para extrair parâmetros de consulta do URL. Se somos todos honestos conosco, não é legal.
Pode ser tedioso e propenso a erros para acertar. Um dos meus segredos é que reutilizei os mesmos
get|set|removeURLParameter
métodos auxiliares em vários apps grandes do Google.com, incluindo o Google Santa Tracker e a Google I/O 2015 na Web.
É hora de uma API adequada que faça isso para nós.
API URLSearchParams
O Chrome 49 implementa o URLSearchParams
da especificação de URL, uma API útil para interagir com parâmetros de consulta de URL. Pense em URLSearchParams
como uma conveniência equivalente a URLs
do que FormData
era a formulários.
O que você pode fazer com ele? Com uma string de URL, é possível extrair facilmente os valores de parâmetro:
// Can also constructor from another URLSearchParams
const params = new URLSearchParams('q=search+string&version=1&person=Eric');
params.get('q') === "search string"
params.get('version') === "1"
Array.from(params).length === 3
for (let p of params) {
console.log(p);
}
set um valor de parâmetro:
params.set('version', 2);
append outro valor de um parâmetro existente:
params.append('person', 'Tim');
params.getAll('person') === ['Eric', 'Tim']
Use delete para excluir parâmetros:
params.delete('person');
Como trabalhar com URLs
Na maioria das vezes, é provável que você trabalhe com URLs completos ou modifique o
URL do app. O construtor URL
pode ser particularmente útil para estes casos:
const url = new URL('https://example.com?foo=1&bar=2');
const params = new URLSearchParams(url.search);
params.set('baz', 3);
params.has('baz') === true
params.toString() === 'foo=1&bar=2&baz=3'
Para fazer mudanças reais no URL, capture os parâmetros, atualize os valores
e use history.replaceState
para atualizar o URL.
// URL: https://example.com?version=1.0
const params = new URLSearchParams(location.search);
params.set('version', 2.0);
window.history.replaceState({}, '', `${location.pathname}?${params}`);
// URL: https://example.com?version=2.0
Aqui, usei strings de modelo do ES6 para reconstruir um URL atualizado a partir do caminho do URL existente do app e dos parâmetros modificados.
A integração com outros URLs de lugares é usada.
Por padrão, enviar FormData
em uma solicitação de API fetch()
cria um corpo de várias partes.
Se você precisar dele, URLSearchParams
fornecerá um mecanismo alternativo para dados POST
que são codificados por URL em vez de várias partes do MIME.
const params = new URLSearchParams();
params.append('api_key', '1234567890');
fetch('https://example.com/api', {
method: 'POST',
body: params
}).then(...)
Embora ainda não tenha sido implementado no Chrome, URLSearchParams
também se integra
ao construtor URL
e às tags a
. Ambas dão suporte ao nosso novo parceiro, fornecendo
uma propriedade somente leitura, .searchParams
, para acessar os parâmetros de consulta:
const url = new URL(location);
const foo = url.searchParams.get('foo') || 'somedefault';
Os links também recebem uma propriedade .searchParams
:
const a = document.createElement('a');
a.href = 'https://example.com?filter=api';
// a.searchParams.get('filter') === 'api';
Detecção de recursos e suporte a navegadores
No momento, o Chrome 49, o Firefox 44 e o Opera 36 são compatíveis com URLSearchParams
.
if ('URLSearchParams' in window) {
// Browser supports URLSearchParams
}
Para polyfills, recomendo aquele em github.com/WebReflection/url-search-params.
Demonstração
Teste o exemplo!
Para conferir URLSearchParams
em um app real, confira o Gerador de ícones do Material Design da Polymer (em inglês). Usei para configurar o estado inicial do app a partir de um link direto. Muito útil :)