Quelle est la différence entre encodeURI et encodeURIComponent ?

Qu'est-ce que encodeURI() ?

encodeURI() est une fonction JavaScript native conçue pour encoder un identifiant de ressource uniforme (URI) complet. Elle convertit les caractères non valides dans une URI en leur équivalent percent-encoded, mais elle préserve intentionnellement les caractères qui ont une signification structurelle au sein d'une URI.

Plus précisément, encodeURI() n'encode pas les caractères suivants : A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #. Cela signifie que la structure globale de l'URL reste intacte après l'encodage.

// encodeURI() préserve la structure de l'URL
const url = 'https://example.com/my page?name=John Doe&city=New York';
console.log(encodeURI(url));
// "https://example.com/my%20page?name=John%20Doe&city=New%20York"
// Remarquez : :, /, ?, & et = ne sont PAS encodés

Ce comportement rend encodeURI() idéale lorsque vous disposez d'une URL complète qui peut contenir des espaces ou des caractères non ASCII, mais dont les caractères structurels (séparateur de protocole, délimiteurs de chemin, marqueurs de chaîne de requête) doivent rester tels quels.

Qu'est-ce que encodeURIComponent() ?

encodeURIComponent() est conçue pour encoder un seul composant d'une URI, comme la valeur d'un paramètre de requête ou un segment de chemin. Contrairement à encodeURI(), elle encode presque tous les caractères spéciaux, y compris ceux qui ont une signification structurelle dans les URL.

Les seuls caractères que encodeURIComponent() n'encode pas sont : A-Z a-z 0-9 - _ . ! ~ * ' ( ). Tout le reste, y compris /, ?, &, =, # et :, est percent-encoded.

// encodeURIComponent() encode tout sauf les caractères non réservés
const value = 'Tom & Jerry / Friends?';
console.log(encodeURIComponent(value));
// "Tom%20%26%20Jerry%20%2F%20Friends%3F"
// Remarquez : &, / et ? SONT encodés

// Construction d'une URL avec un paramètre de requête
const url = 'https://example.com/search?q=' + encodeURIComponent(value);
// "https://example.com/search?q=Tom%20%26%20Jerry%20%2F%20Friends%3F"

Parce qu'elle encode les caractères structurels, vous ne devez jamais utiliser encodeURIComponent() sur une URL complète. Cela encoderait le ://, tous les séparateurs de chemin / et le délimiteur de requête ?, rendant l'URL inutilisable.

Les différences clés en un coup d'œil

Caractéristique	encodeURI()	encodeURIComponent()
Objectif	Encoder une URI complète	Encoder un composant d'URI
Encode /	Non	Oui (%2F)
Encode ?	Non	Oui (%3F)
Encode &	Non	Oui (%26)
Encode =	Non	Oui (%3D)
Encode #	Non	Oui (%23)
Encode :	Non	Oui (%3A)
Encode les espaces	Oui (%20)	Oui (%20)
Encode l'Unicode	Oui	Oui

Quand utiliser chaque fonction

La règle est simple : utilisez encodeURI() lorsque vous souhaitez encoder une URL complète tout en conservant une structure valide. Utilisez encodeURIComponent() lorsque vous souhaitez encoder une seule valeur destinée à être insérée dans une URL.

// Scénario 1 : Encodage d'une URL complète contenant des espaces
const fullUrl = 'https://example.com/my documents/file name.pdf';
const encoded = encodeURI(fullUrl);
// "https://example.com/my%20documents/file%20name.pdf"

// Scénario 2 : Construction d'une URL à partir de plusieurs parties
const baseUrl = 'https://api.example.com/search';
const query = 'price >= 100 & category = books';
const finalUrl = baseUrl + '?q=' + encodeURIComponent(query);
// "https://api.example.com/search?q=price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// Scénario 3 : Encodage d'une URL de redirection en tant que paramètre
const redirectUrl = 'https://example.com/callback?token=abc';
const loginUrl = 'https://auth.example.com/login?redirect=' +
  encodeURIComponent(redirectUrl);
// L'URL de redirection entière est encodée comme une seule valeur de paramètre

Erreurs courantes et comment les éviter

Erreur 1 : Utiliser encodeURI() pour les valeurs des paramètres de requête. Comme encodeURI() n'encode ni & ni =, l'utiliser sur une valeur de paramètre contenant ces caractères corrompra la structure de la chaîne de requête.

// INCORRECT
const bad = 'https://example.com/search?q=' + encodeURI('salt & pepper');
// "https://example.com/search?q=salt%20&%20pepper"
// Le serveur voit q="salt " et un paramètre supplémentaire " pepper"

// CORRECT
const good = 'https://example.com/search?q=' + encodeURIComponent('salt & pepper');
// "https://example.com/search?q=salt%20%26%20pepper"

Erreur 2 : Utiliser encodeURIComponent() sur une URL complète. Cela détruit la structure de l'URL en encodant toutes les barres obliques, les deux-points et les points d'interrogation.

// INCORRECT
console.log(encodeURIComponent('https://example.com/path?key=value'));
// "https%3A%2F%2Fexample.com%2Fpath%3Fkey%3Dvalue"
// Ce n'est plus une URL valide !

// CORRECT
console.log(encodeURI('https://example.com/path?key=value'));
// "https://example.com/path?key=value" (déjà valide, rien à encoder)

Erreur 3 : Le double encodage. Si une chaîne est déjà percent-encoded, l'encoder à nouveau encodera les signes %, transformant %20 en %2520. Vérifiez toujours si une valeur a déjà été encodée avant d'appliquer des fonctions d'encodage.

Une alternative moderne plus sûre est constituée des API URL et URLSearchParams, qui gèrent l'encodage automatiquement et vous aident à éviter entièrement ces pièges.