encodeURIComponent()

Exemple interactif

// Encode les caractres tels que ?,=,/,&,:
console.log(`?x=${encodeURIComponent("test?")}`);
// Rsultat attendu : "?x=test%3F"

console.log(`?x=${encodeURIComponent("")}`);
// Rsultat attendu : "?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"

Syntaxe

encodeURIComponent(uriComponent)

Paramtres

uriComponent

Une chane de caractres encoder comme composant d'URI (un chemin, une chane de requte, un fragment, etc.). Les autres valeurs sont contrainte en chanes de caractres.

Valeur de retour

Une nouvelle chane de caractres qui reprsente le uriComponent fourni, encod comme composant d'URI.

Exceptions

URIError

Leve si uriComponent contient un codet supplant isol.

Description

encodeURIComponent() est une proprit de fonction de l'objet global.

encodeURIComponent() utilise le mme algorithme d'encodage que celui dcrit dans encodeURI(). Il chappe tous les caractres sauf :

AZ az 09 - _ . ! ~ * ' ( )

Par rapport encodeURI(), encodeURIComponent() chappe un ensemble plus large de caractres. Utiliser encodeURIComponent() sur les champs saisis par l'utilisateurice dans les formulaires envoys au serveur cela encode les symboles & qui peuvent tre gnrs par inadvertance lors de la saisie de donnes pour la rfrences de caractres ou d'autres caractres qui ncessitent un encodage/dcodage. Par exemple, si une utilisateurice crit Jack & Jill, sans encodeURIComponent(), l'esperluette peut tre interprte par le serveur comme le dbut d'un nouveau champ et compromettre l'intgrit des donnes.

Pour application/x-www-form-urlencoded (angl.), les espaces doivent tre remplacs par +, il peut donc tre utile de suivre un remplacement encodeURIComponent() par un remplacement supplmentaire de %20 par +.

Exemples

Encodage pour les en-ttes Content-Disposition et Link

L'exemple suivant fournit l'encodage spcial requis dans les paramtres d'en-tte de rponse du serveur UTF-8 Content-Disposition et Link (par exemple, des noms de fichiers en UTF-8) :

const nomFichier = "mon fichier(2).txt";
const enTete = `Content-Disposition: attachment; filename*=UTF-8''${encodeRFC5987ValueChars(
  nomFichier,
)}`;

console.log(enTete);
// "Content-Disposition: attachment; filename*=UTF-8''mon%20fichier%282%29.txt"

function encodeRFC5987ValueChars(str) {
  return (
    encodeURIComponent(str)
      // Ce qui suit cre les squences %27 %28 %29 %2A (Remarquez que
      // l'encodage valide de "*" est %2A, ce qui ncessite d'appeler
      // toUpperCase() pour encoder correctement). Bien que RFC3986
      // rserve "!", la RFC5987 ne le fait pas, il n'est donc pas
      // ncessaire de l'chapper.
      .replace(
        /['()*]/g,
        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
      )
      // Ce qui suit n'est pas requis pour l'encodage en pourcentage
      // selon la RFC5987, on peut donc bnficier d'une meilleure
      // lisibilit sur le fil : |`^
      .replace(/%(7C|60|5E)/g, (str, hex) =>
        String.fromCharCode(parseInt(hex, 16)),
      )
  );
}

Encodage pour RFC3986

La RFC3986 (angl.) plus rcente rserve !, ', (, ) et *, mme si ces caractres n'ont pas d'usage formalis de dlimitation d'URI. La fonction suivante encode une chane de caractres pour le format de composant d'URL conforme RFC3986. Elle encode galement [ et ], qui font partie de la syntaxe URI IPv6. Une implmentation conforme RFC3986 de encodeURI ne doit pas les chapper, ce qui est dmontr dans l'exemple encodeURI().

function encodeRFC3986URIComponent(str) {
  return encodeURIComponent(str).replace(
    /[!'()*]/g,
    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
  );
}

Encoder un codet supplant isol gnre une exception

Une URIError sera leve si vous tentez d'encoder un codet supplant qui ne fait pas partie d'une paire haut-bas. Par exemple :

// Paire haut-bas OK
encodeURIComponent("\uD800\uDFFF"); // "%F0%90%8F%BF"

// Codet supplant haut isol gnre "URIError: malformed URI sequence"
encodeURIComponent("\uD800");

// Codet supplant bas isol gnre "URIError: malformed URI sequence"
encodeURIComponent("\uDFFF");

Vous pouvez utiliser String.prototype.toWellFormed(), qui remplace les codets supplants isols par le caractre de remplacement Unicode (U+FFFD), pour viter cette erreur. Vous pouvez aussi utiliser String.prototype.isWellFormed() pour vrifier si une chane de caractres contient des codets supplants isols avant de la passer encodeURIComponent().

Spcifications

Compatibilit des navigateurs

Voir aussi

• La fonction decodeURI()
• La fonction encodeURI()
• La fonction decodeURIComponent()