Fácil manipulação de URL com URLSearchParams

A API URLSearchParams oferece uma interface consistente para os bits e partes do URL e permite a manipulação trivial da string de consulta (essas informações depois de ?).

Tradicionalmente, os desenvolvedores usam regexs e a divisão de strings para extrair parâmetros de consulta do URL. Se formos honestos, isso não é divertido. Pode ser tedioso e propenso a erros. Um dos meus segredos obscuros é que eu reutilizei os mesmos get|set|removeURLParameter métodos auxiliares em vários apps grandes do Google.com.br, incluindo o Google Santa Tracker e o Google I/O 2015 na Web.

É hora de uma API adequada que faça isso por nós.

API URLSearchParams

Testar a demonstração

O Chrome 49 implementa URLSearchParams da especificação de URL, uma API útil para mexer com parâmetros de consulta de URL. Considero URLSearchParams como uma conveniência equivalente aos URLs, assim como FormData era para formulários.

O que você pode fazer com ele? Com uma string de URL, é possível extrair facilmente os valores dos parâmetros:

// 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);
}

Defina um valor de parâmetro:

params.set('version', 2);

Anexar outro valor a um parâmetro existente:

params.append('person', 'Tim');
params.getAll('person') === ['Eric', 'Tim']

Excluir um ou mais parâmetros:

params.delete('person');

Como trabalhar com URLs

Na maioria das vezes, você provavelmente vai trabalhar com URLs completos ou modificar o URL do app. O construtor URL pode ser ú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, você pode extrair parâmetros, atualizar os valores deles e usar 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 ES6 para reconstruir um URL atualizado do caminho de URL existente do app e dos parâmetros modificados.

Integração com outros URLs de lugares usados

Por padrão, o envio de FormData em uma solicitação de API fetch() cria um corpo de várias partes. Se necessário, URLSearchParams oferece um mecanismo alternativo para POST de dados codificados em URL em vez de multipart mime.

const params = new URLSearchParams();
params.append('api_key', '1234567890');

fetch('https://example.com/api', {
    method: 'POST',
    body: params
}).then(...)

Embora ainda não esteja implementado no Chrome, o URLSearchParams também se integra ao URL e às tags a. Ambos oferecem suporte ao novo amigo, 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

Atualmente, o Chrome 49, o Firefox 44 e o Opera 36 oferecem suporte a URLSearchParams.

if ('URLSearchParams' in window) {
    // Browser supports URLSearchParams
}

Para polyfills, recomendo o que está em github.com/WebReflection/url-search-params.

Demonstração

Teste o exemplo.

Para conferir URLSearchParams em um app real, consulte o Iconset Generator do Polymer. Usei essa abordagem para configurar o estado inicial do app usando um link direto. Muito útil :)