encodeURIComponent vs encodeURI : quand utiliser l'un ou l'autre

Les deux fonctions JavaScript d'encodage d'URL

JavaScript propose deux fonctions intégrées pour l'encodage d'URL : encodeURI() et encodeURIComponent(). Bien qu'elles puissent sembler similaires, utiliser la mauvaise peut entraîner des URL cassées, des failles de sécurité ou une corruption de données. Comprendre la différence est essentiel pour les développeurs web.

encodeURI() - Pour les URI complètes

encodeURI() est conçue pour encoder une URI complète. Elle encode tous les caractères, sauf ceux qui ont une signification particulière dans la structure d'une URI. Plus précisément, elle n'encode PAS :

• Les caractères réservés : ; , / ? : @ & = + $ #
• Les caractères non réservés : lettres, chiffres, - _ . ! ~ * ' ( )

// encodeURI préserve la structure de l'URI
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// Remarque : :, /, ?, =, & ne sont PAS encodés

encodeURIComponent() - Pour les composants d'URI

encodeURIComponent() est conçue pour encoder un seul composant d'une URI (comme la valeur d'un paramètre de requête). Elle encode TOUS les caractères, sauf :

• Les caractères non réservés : lettres, chiffres, - _ . ! ~ * ' ( )

// encodeURIComponent encode tout, sauf les caractères non réservés
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// Remarque : & EST encodé car c'est un caractère réservé

// Utilisation pour la valeur d'un paramètre de requête
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

Erreurs courantes

Erreur n° 1 : utiliser encodeURI pour des valeurs de requête

Si vous utilisez encodeURI() pour encoder la valeur d'un paramètre de requête contenant une esperluette, celle-ci ne sera pas encodée et sera interprétée comme un séparateur de paramètres, ce qui casse votre URL.

// INCORRECT : l'esperluette dans la valeur casse l'URL
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// Le serveur voit : q="Tom " et un paramètre " Jerry" sans valeur

// CORRECT : utilisez encodeURIComponent
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// Le serveur voit correctement : q="Tom & Jerry"

Erreur n° 2 : utiliser encodeURIComponent pour des URL complètes

Si vous utilisez encodeURIComponent() sur une URL entière, elle encodera les deux-points, les barres obliques, les points d'interrogation et les autres caractères structurels, rendant l'URL totalement inutilisable.

Quand utiliser l'un ou l'autre : la règle simple

• Utilisez encodeURI() lorsque vous avez une URI complète qui peut contenir des espaces ou des caractères non-ASCII, mais dont la structure est valide.
• Utilisez encodeURIComponent() lorsque vous encodez une seule donnée destinée à être insérée dans une URI (valeurs de paramètres de requête, segments de chemin, etc.).

L'alternative URLSearchParams

Le JavaScript moderne propose l'API URLSearchParams, qui gère l'encodage automatiquement. C'est souvent la meilleure approche pour construire des chaînes de requête :

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// Ou utilisez l'API URL
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());