Fácil manipulação de URL com URLSearchParams

A API URLSearchParams fornece uma interface consistente para os bits e partes do URL e permite uma manipulação trivial da string de consulta (esse elemento após ?).

Tradicionalmente, os desenvolvedores usam regexs e a divisão de strings para extrair parâmetros de consulta do URL. Se todos somos honestos consigo mesmos, isso não é divertido. Pode ser tedioso e propenso a erros acertar. 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 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 são usados

Por padrão, enviar 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 são compatíveis com URLSearchParams.

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

Para polyfills, recomendamos o disponível em github.com/WebReflection/url-search-params (link em inglês).

Demonstração

Teste a amostra

Para ver o URLSearchParams em um app real, confira o Gerador de Íconeset do Material Design da Polymer. Usei essa abordagem para configurar o estado inicial do app usando um link direto. Isso é muito útil :)