URLSearchParams
Un objet pour lire et construire les paramètres de requête d’une adresse, la partie après le caractère ?, par exemple ?cours=js&page=2.
- Renvoie
- Un nouvel objet
URLSearchParams.
Exemple
#const params = new URLSearchParams('?cours=javascript&page=2&tag=dom&tag=événements')
console.log(params.get('cours'))
console.log(Number(params.get('page')) + 1)
console.log(params.get('trier'))
console.log(params.getAll('tag'))
console.log(params.has('tag'))Définition et utilisation
#URLSearchParams stocke les paramètres de requête sous forme d’une liste de paires nom-valeur. Vous créez l’objet à partir d’une chaîne ("?cours=js&page=2", le ? initial est ignoré), d’un objet ordinaire ({ cours: "js" }) ou d’un tableau de paires. Un objet déjà prêt se trouve aussi dans la propriété searchParams de chaque objet URL.
La méthode get(nom) renvoie la valeur du paramètre ou null quand il n’existe pas, getAll() renvoie toutes les valeurs portant ce nom, has() vérifie sa présence, set() définit une valeur (en remplaçant les précédentes), append() ajoute une nouvelle valeur sous le même nom, et delete() supprime un paramètre. Les valeurs sont toujours des chaînes de caractères, donc convertissez les nombres avec Number().
La méthode toString() recompose les paramètres en une chaîne et encode les caractères spéciaux : l’espace devient +, et les lettres accentuées deviennent des séquences %XX. Vous pouvez parcourir l’objet avec une boucle for...of, et Object.fromEntries(params) le transforme en objet ordinaire. Un objet transmis comme body à fetch() est envoyé dans le même format qu’un formulaire ordinaire.
Syntaxe
#new URLSearchParams(init)
params.get(name)
params.getAll(name)
params.has(name)
params.set(name, value)
params.append(name, value)
params.delete(name)
params.toString()
params.sizeParamètres
#init
optionnel
Une chaîne contenant des paramètres (par ex.location.search), un objet de paires nom-valeur, ou un tableau de paires[nom, valeur].
Plus d’exemples
#const params = new URLSearchParams({ recherche: 'boucle for', niveau: 'débutant' })
params.append('tag', 'js')
params.set('niveau', 'intermédiaire')
console.log(params.toString())
console.log(`/api/cours?${params}`)set() change la valeur d’un paramètre existant à la même place dans la liste. Dans le template literal, l’objet se transforme lui-même en chaîne via toString().
const params = new URLSearchParams('nom=Léa&points=340&badge=start')
for (const [name, value] of params) {
console.log(`${name} = ${value}`)
}
console.log(Object.fromEntries(params))
console.log(params.size)const address = 'https://codeworlds.com/ranking?periode=semaine&page=3'
const url = new URL(address)
url.searchParams.set('page', '1')
url.searchParams.delete('periode')
url.searchParams.append('cours', 'python')
console.log(url.search)
console.log(url.href)Les changements dans url.searchParams mettent immédiatement à jour search et href de l’objet URL.
Compatibilité des navigateurs
#Largement disponible
Fonctionne dans tous les navigateurs modernes, y compris sur mobile. Vous pouvez l’utiliser sans crainte.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- Vous lirez les paramètres de la page actuelle avec
new URLSearchParams(location.search). get()renvoie une chaîne ounull, etNumber(null)vaut0. Donnez une valeur par défaut à un paramètre manquant :Number(params.get("page") ?? 1).- N’encodez pas les valeurs à la main avec
encodeURIComponent()avantset(), elles seraient encodées deux fois.URLSearchParamss’en charge tout seul.
Entrées associées
#- URLUn objet pour créer, lire et modifier des adresses URL. Il décompose une adresse en parties : protocole, hôte, chemin et paramètres.
- locationUn objet contenant des informations sur l’adresse de la page actuelle. Il permet de lire ses parties et de naviguer vers une autre adresse.
- history.pushState()Ajoute une nouvelle entrée à l’historique du navigateur et change l’adresse dans la barre sans recharger la page.
- FormDataRassemble les valeurs des champs d’un formulaire en paires nom-valeur. L’objet obtenu peut être lu ou envoyé au serveur avec fetch().
- Object.fromEntries()Crée un objet à partir d’une liste de paires [clé, valeur].
- fetch()Envoie une requête HTTP et renvoie une promesse avec la réponse du serveur (un objet Response).
Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.