Facile manipolazione degli URL con URLSearchParams

Eric Bidelman
Twitter GitHub Homepage

L'API URLSearchParams fornisce un'interfaccia coerente con tutti i bit e le parti dell'URL e consente una banale manipolazione della stringa di query (quella successiva a ?).

Tradizionalmente, gli sviluppatori utilizzano le espressioni regolari e la suddivisione delle stringhe per estrarre i parametri di query dall'URL. Se siamo tutti onesti con noi stessi, non è divertente. Può essere noioso e soggetto a errori. Uno dei miei oscuri segreti è che ho riutilizzato gli stessi get|set|removeURLParameter metodi di supporto in diverse app Google.com di grandi dimensioni, tra cui Google Santa Tracker e il Google I/O 2015 web.

È arrivato il momento di un'API vera e propria che faccia questo al posto nostro.

API URLSearchParams

Prova la demo

Chrome 49 implementa URLSearchParams dalle specifiche dell'URL, un'API utile per modificare i parametri di query degli URL. URLSearchParams è una convenienza equivalente agli URL come FormData per i moduli.

Cosa puoi farne? Data una stringa URL, puoi estrarre facilmente i valori dei parametri:

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

imposta un valore parametro:

params.set('version', 2);

append un altro valore per un parametro esistente:

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

elimina uno o più parametri:

params.delete('person');

Utilizzo degli URL

La maggior parte delle volte, probabilmente dovrai lavorare con URL completi o modificare l'URL dell'app. Il costruttore URL può essere particolarmente utile nei seguenti casi:

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'

Per apportare modifiche effettive all'URL, puoi recuperare i parametri, aggiornarne i valori e poi usare history.replaceState per aggiornare l'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

Qui ho utilizzato le stringhe modello ES6 per ricostruire un URL aggiornato dal percorso dell'URL esistente dell'app e dai parametri modificati.

Integrazione con altri URL di Places

Per impostazione predefinita, l'invio di FormData in una richiesta API fetch() crea un corpo in più parti. Se ne hai bisogno, URLSearchParams fornisce un meccanismo alternativo ai dati POST con codifica url anziché mimo multiparte.

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

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

Sebbene non sia ancora implementato in Chrome, URLSearchParams si integra anche con il costruttore URL e con i tag a. Entrambi supportano il nostro nuovo amico fornendo una proprietà di sola lettura, .searchParams per l'accesso ai parametri di query:

const url = new URL(location);
const foo = url.searchParams.get('foo') || 'somedefault';

I link ricevono anche una proprietà .searchParams:

const a = document.createElement('a');
a.href = 'https://example.com?filter=api';

// a.searchParams.get('filter') === 'api';

Rilevamento delle funzionalità e supporto del browser

Attualmente, Chrome 49, Firefox 44 e Opera 36 supportano URLSearchParams.

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

Per i polyfill, ti consiglio di utilizzare quello alla pagina github.com/WebReflection/url-search-params.

Demo

Guarda questo campione.

Per vedere URLSearchParams in un'app reale, scopri Polymer's material design Iconset Generator. L'ho utilizzato per configurare lo stato iniziale dell'app da un link diretto. Piuttosto utile :)