Manipulation des URL simplifiée avec URLSearchParams

L'API URLSearchParams fournit une interface cohérente pour les différents éléments de l'URL et permet de manipuler facilement la chaîne de requête (ce qui se trouve après ?).

Traditionnellement, les développeurs utilisent des expressions régulières et la division de chaînes pour extraire les paramètres de requête de l'URL. Soyons honnêtes, ce n'est pas marrant. Il peut être fastidieux et source d'erreurs de trouver la bonne configuration. L'un de mes secrets les plus sombres est que j'ai réutilisé les mêmes get|set|removeURLParameter méthodes d'assistance dans plusieurs grandes applications Google.com, y compris Sur la piste du père Noël avec Google et Google I/O 2015 Web.

Il est temps d'utiliser une API appropriée qui s'en charge pour nous.

API URLSearchParams

Essayer la démo

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

Alors, que pouvez-vous en faire ? À 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 pour un paramètre existant :

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

supprimer 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 à 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 emplacements où les URL sont utilisées

Par défaut, l'envoi de FormData dans une requête API fetch() crée un corps multipart. Si nécessaire, URLSearchParams fournit un autre mécanisme pour les données POST encodées au format URL plutôt qu'au format MIME multipart.

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. Tous deux prennent en charge notre nouvel ami 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 obtiennent également 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é des 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 réelle, consultez le générateur de jeux d'icônes Material Design de Polymer. Je l'ai utilisé pour configurer l'état initial de l'application à partir d'un lien profond. Plutôt pratique :)