Que fait encodeURIComponent ? Une explication simple avec des exemples

Si vous avez créé une URL en JavaScript, vous avez probablement rencontré encodeURIComponent, et peut-être son frère similaire, encodeURI. Utiliser le mauvais est un bug classique qui rompt les liens de manière subtile. Voici une explication claire de ce que fait encodeURIComponent, avec des exemples et une règle simple pour choisir entre les deux.

Ce que ça fait

encodeURIComponent prend une chaîne et remplace tout caractère non sécurisé dans une URL par son équivalent codé en pourcentage. Un espace devient %20, une esperluette devient %26, un signe égal devient %3D, un point d'interrogation devient %3F, et ainsi de suite. Le but est de faire en sorte qu'un morceau de texte puisse être déposé en toute sécurité dans une URL en tant que valeur, terme de recherche, paramètre, cible de redirection, sans que les caractères spéciaux ne soient mal interprétés en tant que structure d'URL. Il code tout ce qui pourrait causer un problème, ce qui correspond exactement à ce que vous souhaitez pour une valeur unique.

Un exemple concret

Supposons que vous souhaitiez créer une URL de recherche pour la requête « chats et chiens ». Si vous le concaténez simplement, vous obtenez ...?q=cats & dogs, qui casse, l'esperluette est lue comme séparateur de paramètre et l'espace est illégal. Exécutez d'abord la valeur via encodeURIComponent et "cats & dogs" devient cats%20%26%20dogs, vous donnant ...?q=cats%20%26%20dogs, que le serveur lit correctement comme la valeur unique "cats & dogs". L'encodage préserve la signification de vos données en échappant aux caractères qui seraient autrement structurels.

encodeURIComponent vs encodeURI

La différence est ce que chacun laisse tranquille. encodeURIComponent encode tout ce qui est réservé, y compris les caractères de la structure de l'URL comme /? & = #, car cela suppose que vous encodez une valeur qui va dans une URL. encodeURI n'encode délibérément pas ces caractères de structure, car il suppose que vous encodez une URL entière déjà construite et que vous souhaitez la garder fonctionnelle. Ainsi, encodeURI('https://x.com?a=bc') conserve le ://, le ? et le = intacts et ne corrige que l'espace, tandis que encodeURIComponent les échapperait tous. Utilisez le composant pour les morceaux, encodeURI pour une URL entière.

La règle simple

Voici la règle qui vous évite les ennuis : si vous encodez une valeur qui entre dans une URL, un terme de recherche, une valeur de paramètre, un segment de chemin, une cible de redirection, utilisez encodeURIComponent. Si vous codez une URL entière et que vous souhaitez qu'elle reste une URL fonctionnelle, utilisez encodeURI. Lorsque vous n'êtes pas sûr, vous souhaitez presque toujours encodeURIComponent, car vous encodez presque toujours une valeur, pas une URL entière. Bien faire les choses évite les bogues de création d’URL les plus courants.

Attention au double encodage

Un piège : ne jamais exécuter encodeURIComponent sur une chaîne déjà encodée. Si vous encodez une valeur deux fois, les signes de pourcentage eux-mêmes sont codés, %20 devient %2520 et le lien est rompu. Encodez uniquement du texte brut et non codé. Si vous n'êtes pas sûr qu'une chaîne soit déjà codée, décodez-la d'abord, puis encodez-la exactement une fois. Cette erreur de double encodage est à l’origine du mystérieux %2520 que vous voyez parfois dans les URL cassées.