Number.prototype.toLocaleString()

La méthode toLocaleString() permet de renvoyer une chaîne de caractères représentant un nombre en tenant compte de la locale.

Les arguments locales et options permettent à l'application de spécifier les options de formatage selon la langue utilisée. Ces arguments ont un effet sur le comportement de la fonction. Les implémentations passées, qui ignoraient les arguments locales et options se basaient uniquement sur l'implémentation pour ce qui concernait la locale et le format.

Syntaxe

objetNumber.toLocaleString([locales [, options]])

Paramètres

Voir la section compatibilité des navigateurs afin de voir quels navigateurs supportent les arguments locales et options. L'exemple Vérifier le support des arguments locales et options permet de détecter cette fonctionnalité.

locales

Paramètre optionnel. Une chaine de caractères avec un identifiant de langue BCP 47, ou un tableau de ce type de chaine de caractères. Pour le format général et l'interprétation de l'argument locales, voir la page Intl. Les clefs d'extensions Unicode suivantes sont autorisées :

nu

Le système numérique à utiliser. Parmi les valeurs possibles, on a : "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".

options

Paramètre optionnel. Un objet avec certaines ou toutes les propriétés suivantes :

localeMatcher

L'algorithme de correspondance à utiliser pour la locale. Les valeurs possibles sont "lookup" et "best fit" ; le défaut est "best fit". Pour des informations sur cette option, voir la page Intl.

style

Le style de formatage. Les valeurs possibles sont "decimal" pour l'affichage de nombres simple, "currency" pour un affichage en fonction de la devise et "percent" pour afficher des pourcentages. La valeur par défaut est "decimal".

currency

La devise à utiliser pour le formatage. Les valeurs possibles sont les codes ISO 4217 pour les devises, tels que "USD" pour le dollar américain, "EUR" pour l'euro, ou "CNY" pour le yuan chinois. Voir la page listant les codes actuels pour les devises et les fonds (en anglais). Il n'y a pas de valeur par défaut. Si le style choisi avec l'option style est "currency", la propriété currency doit être définie.

currencyDisplay

La façon d'afficher la devise dans le format courant. Les valeurs possibles sont "symbol" qui permet d'utiliser un symbole localisé comme '€', "code" qui affichera le code ISO de la devise (voir ci-avant), "name"  affichera un nom localisé pour la devise comme "dollar". La valeur par défaut est "symbol".

useGrouping

Cette option indique si on doit utiliser des séparateurs de groupes (comme les séparateurs de milliers ou autres comme lakhs et crores). Les valeurs possibles sont true et false. La valeur par défaut true.

Les propriétés suivantes peuvent être classées en deux groupes. Dans le premier on aura minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits et dans le second on aura minimumSignificantDigits et maximumSignificantDigits. S'il existe une option définie pour le second groupe, les options du premier groupe seront ignorées.

minimumIntegerDigits

Le nombre minimal de chiffres à utiliser pour la partie entière. Les valeurs possibles sont comprises entre 1 to 21. La valeur par défaut est 1.

minimumFractionDigits

Le nombre minimal de chiffres à utiliser pour la partie fractionnaire. Les valeurs possibles sont comprises entre 0 et 20. Pour les formats "decimal" et "percent", la valeur par défaut est 0. La valeur par défaut pour le formatage monétaire ("currency") correspond au nombre de chiffres défini par la liste de codes de devises ISO 4217, si cette valeur n'est pas définie dans cette liste, on aura 2 chiffres.

maximumFractionDigits

Le nombre maximal de chiffres à utiliser pour représenter la partie fractionnaire. Les valeurs possibles sont comprises entre 0 et 20. Pour le format "decimal", la valeur par défaut est le maximum entre 3 et minimumFractionDigits. Pour le format monétaire ("currency"), la valeur par défaut est le maximum entre  minimumFractionDigits et le nombre de chiffres prévus par la liste ISO 4217 des codes de devises (ou 2 si cette information n'est pas disponible dans cette liste). Pour le format en pourcent, la valeur par défaut est le maximum entre minimumFractionDigits et 0.

minimumSignificantDigits

Le nombre minimal de chiffres significatifs à utiliser. Les valeurs possibles sont comprises entre 1 et 21. La valeur par défaut est 1.

maximumSignificantDigits

Le nombre maximal de chiffres significatifs à utiliser. Les valeurs possibles sont comprises entre 1 et 21. La valeur par défaut est minimumSignificantDigits.

Valeur de retour

Une chaîne de caractères qui représente le nombre indiqué en tenant compte de la locale.

Exemples

Utiliser toLocaleString()

En utilisant la fonction simplement, sans spécifier de locale, la chaîne est formatée dans la locale par défaut et avec des options par défaut.

var nombre = 3500;

console.log(number.toLocaleString()); // Affichera "3 500" pour la locale française

Vérifier le support des arguments locales et options

Les arguments locales et options ne sont pas supportés par tous les navigateurs. Afin de vérifier qu'une implémentation les prend en charge, on se base sur le fait que les balises de langues incorrectes renvoient une exceptionRangeError :

function testSupporttoLocaleString() {
    var nombre = 0;
    try {
        nombre.toLocaleString("i");
    } catch (e) {
        return e​.name === "RangeError";
    }
    return false;
}

Avant ES5.1, il n'était pas nécessaire pour les implémentations de provoquer une erreur d'intervalle si toLocaleString était appelé avec des arguments.

Afin de vérifier le support pour tous les environnements, y compris ceux qui supportent ECMA-262 avant la version 5.1, on peut tester les fonctionnalités définies dans ECMA-402, directement sur Number.prototype.toLocaleString :

function toLocaleStringSupportsOptions() {
  return !!(typeof Intl == 'object' && Intl && typeof Intl.NumberFormat == 'function');
}

Cela permet de tester la présence d'un objet global Intl, de vérifier que celui-ci n'est pas null et qu'il a une méthode NumberFormat.

Utiliser l'argument locales

Cet exemple illustre les variations possibles entre les différents formats localisés. Afin que le format de langue utilisé soit celui de votre utilisateur, assurez-vous de fournir la langue utilisée (ainsi que des langues de secours) en utilisant l'argument locales :

var nombre= 123456.789;

// Pour la locale allemande, on utilise un point comme séparateur
// pour les milliers et une virgule comme séparateur décimal
console.log(nombre.toLocaleString("de-DE"));
// → 123.456,789

// Les locales arabes, dans la plupart des pays arabophones, utilisent
// les chiffres arabes
console.log(nombre.toLocaleString("ar-EG"));
// → ١٢٣٤٥٦٫٧٨٩

// En Inde, on utilise des séparateurs de milliers/lakh/crore
console.log(nombre.toLocaleString("en-IN"));
// → 1,23,456.789

// La clé d'extension nu indique un système numérique, ici le système chinois décimal
console.log(nombre.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// → 一二三,四五六.七八九

// quand on souhaite utiliser un langage qui n'est pas supporté, on peut
// inclure un langage de secours. Exemple ici avec le balinais et l'indonésien
console.log(nombre.toLocaleString(["ban", "id"]));
// → 123.456,789

Utiliser l'argument options

Les résultats fournis par toLocaleString peuvent être déclinés en utilisant l'argument options :

var nombre = 123456.789;

// on formate selon une devise
console.log(nombre.toLocaleString("de-DE", {style: "currency", currency: "EUR"}));
// → 123.456,79 €

// le yen japonais ne possède pas de centimes
console.log(nombre.toLocaleString("ja-JP", {style: "currency", currency: "JPY"}))
// → ￥123,457

// on se limite à trois chiffres significatifs
console.log(nombre.toLocaleString("en-IN", {maximumSignificantDigits: 3}));
// → 1,23,000

Performance

Lors du formatage de beaucoup de nombres, il est préférable de créer un objet NumberFormat et d'utiliser sa méthode NumberFormat.format.

Spécifications

Compatibilité des navigateurs

Voir aussi

• Number.prototype.toString()