Guide de l'Encodage URL

L'encodage d'URL — formellement percent-encoding — est le mécanisme que le web utilise pour transporter des caractères spéciaux à l'intérieur des URLs. Chaque fois qu'un utilisateur saisit une recherche avec des espaces, chaque fois qu'une API reçoit un query avec une esperluette, chaque fois qu'une redirection préserve un nom de fichier non-ASCII, c'est le percent-encoding qui fait que ça marche. Ce guide couvre les règles, les deux API JavaScript et les erreurs qui vous mordront.

Réservés vs non réservés

La RFC 3986 répartit les caractères en deux groupes. Les non réservés — A–Z, a–z, 0–9 et - _ . ~ — sont toujours sûrs. Les réservés — : / ? # [ ] @ ! $ & ' ( ) * + , ; = — ont un sens structurel (séparer schéma et chemin, clé et valeur, composant et composant) et doivent être encodés lorsqu'ils apparaissent comme donnée plutôt que structure. Tout le reste (espaces, Unicode, octets binaires) doit toujours être encodé.

La règle d'encodage

Chaque octet à échapper devient un signe pour-cent suivi de deux chiffres hexadécimaux. Un espace est %20, une esperluette est %26, un tiret cadratin fait trois octets UTF-8 et donc trois séquences : %E2%80%94. Les décodeurs inversent octet par octet.

encodeURI vs encodeURIComponent

JavaScript propose deux fonctions qui piègent tout le monde au moins une fois. encodeURI(str) suppose que str est une URL complète et laisse les réservés tranquilles (slashes, deux-points, points d'interrogation survivent). encodeURIComponent(str) suppose que str est un seul composant — un segment de chemin ou une valeur — et échappe tous les réservés. Règle pratique : pour une valeur de query string destinée à ?clé=valeur, toujours encodeURIComponent. Pour nettoyer une URL complète sans casser sa structure, encodeURI.

Erreurs courantes

• Double encodage — encoder quelque chose de déjà encodé. %20 devient %2520, le décodeur voit un %20 littéral, et l'URL ne contient plus d'espace.
• Mauvaise fonction sur la mauvaise partie — utiliser encodeURIComponent sur une URL entière massacre le séparateur de schéma.
• Oublier les espaces dans les form-data — les POST HTML avec application/x-www-form-urlencoded encodent les espaces en +, pas en %20. Pour tout le reste, utilisez %20.
• Supposer autre chose que UTF-8 — l'encodage URL moderne est toujours UTF-8 d'abord, puis percent-encoding. Les systèmes hérités qui utilisaient Latin-1 ou Shift_JIS paraissent similaires mais produisent du n'importe quoi en non-ASCII.

Quand choisir l'une ou l'autre

Utilisez encodeURIComponent chaque fois que vous composez dynamiquement une valeur de query. Utilisez encodeURI quand vous avez une URL fournie par l'utilisateur (peut-être avec de l'Unicode dans le chemin) que vous voulez rendre sûre sans casser sa structure. Décodez avec decodeURIComponent sauf si vous voulez délibérément préserver des réservés — auquel cas vous n'auriez sans doute pas dû les encoder.