Manipulation des URL simplifiée avec URLSearchParams

L'API URLSearchParams fournit une interface cohérente aux éléments de l'URL et permet une manipulation simple de la chaîne de requête (éléments situés après ?).

Traditionnellement, les développeurs utilisent des expressions régulières et la division de chaîne pour extraire les paramètres de requête de l'URL. Si nous sommes tous honnêtes avec nous-mêmes, ce n'est pas drôle. Il peut être fastidieux et sujet aux erreurs. L'un de mes secrets les plus sombres est que j'ai réutilisé les mêmes méthodes d'assistance get|set|removeURLParameter dans plusieurs grandes applications Google.com, y compris Google Santa Tracker et le site Web Google I/O 2015.

Il est temps qu'une API appropriée effectue ces tâches à notre place.

API URLSearchParams

Essayer la démo

Chrome 49 implémente URLSearchParams à partir de la spécification de l'URL, une API utile pour manipuler les paramètres de requête d'URL. Je considère URLSearchParams comme une commodité équivalente aux URL, comme FormData l'était pour les formulaires.

Que pouvez-vous faire avec ? À partir d'une chaîne d'URL, vous pouvez facilement extraire les valeurs des paramètres:

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

définir une valeur de paramètre:

params.set('version', 2);

ajouter une autre valeur à un paramètre existant:

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

supprimez un ou plusieurs paramètres :

params.delete('person');

Utiliser des URL

La plupart du temps, vous travaillerez probablement avec des URL complètes ou modifierez l'URL de votre application. Le constructeur URL peut être particulièrement utile dans les cas suivants:

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'

Pour apporter des modifications réelles à l'URL, vous pouvez récupérer des paramètres, mettre à jour leurs valeurs, puis utiliser history.replaceState pour mettre à jour 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

Ici, j'ai utilisé des chaînes de modèle ES6 pour reconstruire une URL mise à jour à partir du chemin d'URL existant de l'application et des paramètres modifiés.

Intégration à d'autres URL de lieux

Par défaut, l'envoi de FormData dans une requête d'API fetch() crée un corps multiparti. Si vous en avez besoin, URLSearchParams fournit un mécanisme alternatif aux données POST encodées au format URL plutôt qu'aux données MIME en plusieurs parties.

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

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

Bien qu'il ne soit pas encore implémenté dans Chrome, URLSearchParams s'intègre également au constructeur URL et aux balises a. Les deux prennent en charge notre nouveau collègue en fournissant une propriété en lecture seule, .searchParams, pour accéder aux paramètres de requête:

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

Les liens disposent également d'une propriété .searchParams:

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

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

Détection des fonctionnalités et compatibilité avec les navigateurs

Actuellement, Chrome 49, Firefox 44 et Opera 36 sont compatibles avec URLSearchParams.

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

Pour les polyfills, je vous recommande celui disponible sur github.com/WebReflection/url-search-params.

Démo

Essayez l'exemple.

Pour voir URLSearchParams dans une application concrète, consultez le générateur d'icônes Material Design de Polymer. Je l'ai utilisé pour configurer l'état initial de l'application à partir d'un lien profond. Très pratique :)