API URL JavaScript

Introduction aux objets URL JavaScript

JavaScript fournit une interface URL intégrée et puissante pour construire, analyser et manipuler les URL. Plutôt que de découper des chaînes avec des expressions régulières ou des appels manuels à split() — qui échouent sur des cas particuliers comme les ports, les caractères encodés et les composants manquants — l'objet URL analyse une adresse en parties structurées et adressables individuellement.

L'interface URL est disponible nativement dans les navigateurs et dans Node.js (c'est une variable globale, aucun require n'est nécessaire). Ce guide explique comment créer et analyser des URL, lire et modifier chaque composant, travailler avec les chaînes de requête via URLSearchParams, et gérer des tâches courantes telles que la construction de requêtes API et le suivi de liens.

Créer et analyser des URL avec JavaScript

Création d'une URL de base

Pour créer un objet URL, passez la chaîne d'adresse au constructeur URL. Si la chaîne n'est pas une URL absolue valide, le constructeur lève une TypeError :

const url = new URL("https://www.w3docs.com");

Analyse des composants d'une URL

Une fois l'objet URL créé, vous pouvez lire n'importe quelle partie via une propriété dédiée :

L'ensemble complet des composants pour une URL comme https://user:[email protected]:8080/path?q=1#top est :

Valider une URL avant de l'analyser

Comme le constructeur lève une exception sur une entrée invalide, validez d'abord les chaînes non fiables. La méthode statique URL.canParse() renvoie un boolean sans lever d'exception :

Manipuler les objets URL

Travailler avec la chaîne de requête via URLSearchParams

Chaque URL expose une propriété searchParams — un objet URLSearchParams actif dont les modifications sont répercutées directement sur l'URL. C'est la méthode recommandée pour modifier une chaîne de requête, car elle gère l'encodage pour vous. L'exemple ci-dessous utilise un objet URLSearchParams séparé pour montrer comment les éléments s'assemblent :

En pratique, on omet généralement l'objet intermédiaire et on modifie url.searchParams directement — cela mute l'URL en place :

Clés répétées et itération

Les chaînes de requête peuvent contenir la même clé plusieurs fois (par exemple ?tag=js&tag=web). get() renvoie uniquement la première correspondance, tandis que getAll() renvoie toutes les valeurs. Vous pouvez également itérer sur toutes les paires avec for...of :

Explication

• Initialisation :
  • L'objet URL est créé avec une URL de base qui contient déjà un paramètre de requête (initial=123).
• Objet URLSearchParams :
  • URLSearchParams est initialisé avec url.search, qui contient la chaîne de requête de l'URL.
• Ajouter un paramètre :
  • La méthode .set() est utilisée pour ajouter un nouveau paramètre (key=value) à la chaîne de requête. Si la clé existe déjà, sa valeur est mise à jour ; sinon, la paire clé-valeur est ajoutée.
• Lire un paramètre :
  • La méthode .get() récupère la valeur du paramètre identifié par la clé (key), qui est ensuite affichée dans la console.
• Supprimer un paramètre :
  • La méthode .delete() supprime le paramètre identifié par la clé (initial). Cela illustre comment retirer un paramètre de la chaîne de requête.
• Mettre à jour la recherche de l'URL :
  • Après avoir modifié les paramètres, la propriété search de l'URL est mise à jour avec la représentation string de l'objet URLSearchParams.
• Résultat :
  • Enfin, l'URL modifiée est affichée dans la console, montrant l'effet des opérations.

Modifier le chemin et le fragment

Voici un extrait JavaScript qui montre comment modifier le chemin (pathname) et le fragment (hash) d'une URL :

Explication

• Initialisation de l'objet URL :
  • L'objet URL est initialement créé à partir d'une string représentant une URL complète. Cette URL comprend un chemin, une chaîne de requête et un fragment.
• Modification du chemin :
  • La propriété pathname de l'objet URL est définie sur un nouveau chemin (/path/to/resource). Cette propriété spécifie le chemin ou la route sur le serveur.
• Modification du fragment :
  • La propriété hash est mise à jour à "section". Dans les URL, le fragment représente un signet dans la page, souvent utilisé pour faire défiler vers une section spécifique.
• Journalisation des changements :
  • L'URL originale est affichée avant les modifications pour montrer l'état initial.
  • Après les modifications, le nouvel état de l'URL est affiché pour illustrer les effets du changement de pathname et de hash.

Utilisation avancée des objets URL

Gestion des URL relatives

L'objet URL peut également résoudre des URL relatives par rapport à une URL de base, ce qui est particulièrement utile pour les applications web qui gèrent des liens dynamiques :

Travailler avec l'encodage des URL

Lorsque vous traitez des URL contenant des caractères qui nécessitent un encodage, l'objet URL les gère automatiquement, garantissant ainsi la validité des URL :

Pour gérer les fichiers locaux ou les blobs, URL.createObjectURL() génère une string URL temporaire référençant l'objet en mémoire, ce qui est utile pour prévisualiser des images ou télécharger des fichiers directement depuis JavaScript.

Exemples pratiques de manipulation d'URL

Suivi des URL de campagne

Vous pouvez utiliser les objets URL pour gérer efficacement les URL de campagne, couramment utilisées en marketing digital pour suivre les performances de diverses actions marketing :

Intégration avec les API Web

Les objets URL s'associent naturellement à l'API Fetch : vous pouvez passer une instance de URL directement à fetch(), et searchParams garantit que la chaîne de requête est correctement encodée. Une fois la requête résolue, vous analysez généralement la réponse avec les méthodes JSON :

Alternative moderne (async/await) :

async function fetchPosts() {
  const apiUrl = new URL("https://jsonplaceholder.typicode.com/posts");
  apiUrl.searchParams.set("userId", "1");
  const response = await fetch(apiUrl);
  const data = await response.json();
  console.log(data[0]); // Outputs the first post by user with userId 1
}

Pièges courants

• Le constructeur lève une exception sur une entrée invalide. new URL("example.com") échoue car il n'y a pas de protocole. Fournissez une URL absolue complète, passez une URL de base en second argument, ou protégez-vous avec URL.canParse().
• Les string relatives nécessitent une base. new URL("/about") lève une exception seul ; new URL("/about", "https://www.w3docs.com") résout correctement.
• origin est en lecture seule. Vous ne pouvez pas assigner à url.origin. Modifiez protocol, hostname ou port individuellement à la place.
• get() renvoie uniquement la première valeur. Pour les clés qui peuvent se répéter, utilisez getAll().
• La normalisation est automatique. La lecture de href peut ajouter un slash final (https://w3docs.com devient https://w3docs.com/) et encoder les caractères réservés en pourcentage. Comparez des URL analysées, pas des string brutes, lors des vérifications d'égalité.
• L'ordre de searchParams est l'ordre d'insertion. Utilisez params.sort() si vous avez besoin d'une chaîne de requête canonique et stable pour la mise en cache ou la signature.

Conclusion

L'objet URL JavaScript est un outil robuste pour gérer tous les aspects de la manipulation et de l'analyse des URL. En maîtrisant ses propriétés et ses méthodes, les développeurs peuvent simplifier les interactions de leur application web avec les URL, améliorant ainsi la fonctionnalité et l'expérience utilisateur. Que vous gériez des structures d'URL complexes, que vous vous intégriez à des API ou que vous suiviez des campagnes marketing, l'objet URL offre un moyen fiable et efficace de travailler avec les adresses web en JavaScript.

Pratique