Fácil manipulação de URL com URLSearchParams

A API URLSearchParams fornece uma interface consistente para as partes do URL e permite a manipulação trivial da string de consulta (o que vem depois de ?).

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

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

API URLSearchParams

Teste 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. Eu penso no URLSearchParams como uma conveniência equivalente aos URLs, assim como o FormData era para os formulários.

O que você pode fazer com ele? Dada uma string de URL, é fácil extrair valores de 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);
}

definir um valor de parâmetro:

params.set('version', 2);

Anexar outro valor a um parâmetro atual:

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ê vai trabalhar com URLs completos ou modificar o URL do seu 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, pegue os parâmetros, atualize os valores deles 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 com base no caminho do URL atual do app e nos parâmetros modificados.

Integração com outros lugares em que os URLs são 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, o URLSearchParams oferece um mecanismo alternativo para dados POST que são codificados por URL em vez de MIME multipart.

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 construtor URL e às tags a. Ambos oferecem suporte ao nosso 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 compatibilidade com navegadores

Atualmente, 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 o que está em github.com/WebReflection/url-search-params.

Demonstração

Teste o exemplo.

Para ver o URLSearchParams em um app real, confira o gerador de conjuntos de ícones do Material Design do Polymer (em inglês). Eu o usei para configurar o estado inicial do app de um link direto. Muito útil :)