Cette page a été traduite à partir de l'anglais par la communauté.Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.
encodeURIComponent()
Baseline Widely available
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.
La fonctionencodeURIComponent() permet d'encoder un composant d'un Uniform Resource Identifier (URI) en remplaçant chaque exemplaire de certains caractères par une, deux, trois ou quatres séquences d'échappement UTF-8 correspondantes (quatre séquences seront utilisées uniquement lorsque les caractères à encoder sont composés de deux caractères «surrogate »).
Exemple interactif
// Encodes characters such as ?,=,/,&,:console.log(`?x=${encodeURIComponent("test?")}`);// Expected output: "?x=test%3F"console.log(`?x=${encodeURIComponent("шеллы")}`);// Expected output: "?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"Syntaxe
encodeURIComponent(str);Paramètres
strUne chaîne de caractères qui correspond à un composant d'URI.
Valeur de retour
Une nouvelle chaîne de caractères qui représente un composant d'URI obtenu en encodant la chaîne passée en argument.
Description
encodeURIComponent() échappe tous les caractères sauf : les lettres de l'alphabet latin, les chiffres (arabes) et- _ . ! ~ * ' ( )
La méthodeencodeURIComponent() diffère de la méthodeencodeURI() par rapport aux caractères qui sont encodés :
var set1 = ";,/?:@&=+$"; // Caractères réservésvar set2 = "-_.!~*'()"; // Caractères non-réservésvar set3 = "#"; // Croisillonvar set4 = "ABC abc 123"; // Caractères alphanumériques et espaceconsole.log(encodeURI(set1)); // ;,/?:@&=+$console.log(encodeURI(set2)); // -_.!~*'()console.log(encodeURI(set3)); // #console.log(encodeURI(set4)); // ABC%20abc%20123 (l'espace est encodé en %20)console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24console.log(encodeURIComponent(set2)); // -_.!~*'()console.log(encodeURIComponent(set3)); // %23console.log(encodeURIComponent(set4)); // ABC%20abc%20123 (l'espace est encodé en %20)Une exceptionURIError sera levée lorsqu'on utilise cette fonction sur un unique demi-codet qui est censé faire partie d'une paire de demi-codets :
// la paire de demi-codets : OKconsole.log(encodeURIComponent("\uD800\uDFFF"));// seul le demi-codet supérieur : "URIError: malformed URI sequence"console.log(encodeURIComponent("\uD800"));// seul le demi-codet inférieur : "URIError: malformed URI sequence"console.log(encodeURIComponent("\uDFFF"));Afin d'éviter des requêtes inattendues vers le serveur, il est conseillé d'utiliser la fonctionencodeURIComponent() pour n'importe quel paramètre qui aurait été saisi par l'utilisateur et qui ferait partie d'un URI. Ainsi, si un utilisateur peut saisir "Thym &access=admin" dans une variablecommentaire et qu'on n'utilise pasencodeURIComponent(), on obtiendra la chaînecommentaire=Thym%20&access=admin. On voit ici que l'esperluette (&) et le signe égal forment une nouvelle paire clé/valeur. Au lieu d'avoir une clé POSTcommentaire égale à "Thym &access=admin", on aura deux clés POST, l'une égale à "Thym" et une seconde (access) égale àadmin.
Pourapplication/x-www-form-urlencoded, les espaces sont remplacés par un '+', aussi, dans ce cas, on pourra ajouter un remplacement supplémentaire aprèsencodeURIComponent() pour remplacer "%20" par "+".
Pour utiliser une fonction qui respecte laRFC 3986, plus stricte (qui réserve les caractères !, ', (, ), et * même si ces caractères n'ont pas d'usage normalisé), on pourra utiliser la fonction suivante :
function fixedEncodeURIComponent(str) { return encodeURIComponent(str).replace(/[!'()*]/g, function (c) { return "%" + c.charCodeAt(0).toString(16); });}Exemples
Dans l'exemple qui suit, on utilise une méthode spéciale pour l'encodage afin d'utiliser les paramètres d'en-tête de réponseContent-Disposition etLink (pour, par exemple, représenter des noms de fichiers en UTF-8) :
var nomFichier = "mon fichier(2).txt";var header = "Content-Disposition: attachment; filename*=UTF-8''" + encodeRFC5987ValueChars(nomFichier);console.log(header);// affiche "Content-Disposition: attachment; filename*=UTF-8''mon%20fichier%282%29.txt"function encodeRFC5987ValueChars(str) { return ( encodeURIComponent(str) // Bien que la RFC 3986 réserve "!", RFC 5987 ne réserve pas ce caractère, // il n'est donc pas nécessaire l'échapper .replace(/['()]/g, escape) // c'est-à-dire %27 %28 %29 .replace(/\*/g, "%2A") // Selon la RFC 5987 ce qui suit n'est pas nécessairement requis // on peut donc bénéficier d'un peu plus de lisibilité : |`^ .replace(/%(?:7C|60|5E)/g, unescape) );}// Voici une autre version équivalentefunction encodeRFC5987ValueChars2(str) { return ( encodeURIComponent(str) // Bien que la RFC 3986 réserve "!", RFC 5987 ne réserve pas ce caractère, // il n'est donc pas nécessaire l'échapper .replace(/['()*]/g, (c) => "%" + c.charCodeAt(0).toString(16)) // i.e., %27 %28 %29 %2a // on notera que l'encodage valide pour "*" est %2A et qui faut donc appeler toUpperCase() // pour encoder exactement. // Selon la RFC 5987 ce qui suit n'est pas nécessairement requis // on peut donc bénéficier d'un peu plus de lisibilité : |`^ .replace(/%(7C|60|5E)/g, (str, hex) => String.fromCharCode(parseInt(hex, 16)), ) );}Spécifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-encodeuricomponent-uricomponent |