Fácil manipulação de URL com URLSearchParams

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

Testar a demonstração

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 :)