BigInt : méthode toLocaleString()

Exemple interactif

const bigint = 123456789123456789n;

// L'allemand utilise des points pour séparer les milliers
console.log(bigint.toLocaleString("de-DE"));
// Sortie attendue : "123.456.789.123.456.789"

// Demander un format monétaire
console.log(
  bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// Sortie attendue : "123.456.789.123.456.789,00 €"

Syntaxe

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Paramètres

Les paramètres locales et options personnalisent le comportement de la fonction et permettent aux applications de spécifier la langue dont les conventions de formatage doivent être utilisées.

Dans les implémentations qui prennent en charge l'API Intl.NumberFormat, ces paramètres correspondent exactement à ceux du constructeur Intl.NumberFormat(). Les implémentations sans prise en charge de Intl.NumberFormat doivent ignorer ces deux paramètres, rendant la locale utilisée et la forme de la chaîne retournée entièrement dépendantes de l'implémentation.

locales Facultatif

Une chaîne de caractères avec une étiquette de langue BCP 47, ou un tableau de telles chaînes. Correspond au paramètre locales du constructeur Intl.NumberFormat().

Dans les implémentations sans prise en charge de Intl.NumberFormat, ce paramètre est ignoré et la locale de l'hôte est généralement utilisée.

options Facultatif

Un objet ajustant le format de sortie. Correspond au paramètre options du constructeur Intl.NumberFormat().

Dans les implémentations sans prise en charge de Intl.NumberFormat, ce paramètre est ignoré.

Voir le constructeur Intl.NumberFormat() pour plus de détails sur ces paramètres et leur utilisation.

Valeur de retour

Une chaîne de caractères représentant le BigInt donné selon les conventions spécifiques à la langue.

Dans les implémentations avec Intl.NumberFormat, cela équivaut à new Intl.NumberFormat(locales, options).format(number).

Exemples

Utiliser toLocaleString()

L'utilisation basique de cette méthode sans définir de locale renvoie une chaîne de caractères formatée dans la locale par défaut et avec les options par défaut.

const bigint = 3500n;

console.log(bigint.toLocaleString());
// Affichera "3500" en français

Vérifier la prise en charge des paramètres locales et options

Les paramètres locales et options peuvent ne pas être pris en charge dans toutes les implémentations, car la prise en charge de l'API d'internationalisation est optionnelle et certains systèmes peuvent ne pas disposer des données nécessaires. Pour les implémentations sans prise en charge de l'internationalisation, toLocaleString() utilise toujours la locale du système, ce qui peut ne pas correspondre à vos attentes. Toute implémentation qui prend en charge les paramètres locales et options doit prendre en charge l'API Intl, vous pouvez donc vérifier l'existence de cette dernière pour détecter la prise en charge :

function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.NumberFormat === "function"
  );
}

Utiliser locales

Cet exemple montre certaines des variations dans les formats de nombres localisés. Pour obtenir le format de la langue utilisée dans l'interface utilisateur de votre application, veillez à spécifier cette langue (et éventuellement des langues de secours) à l'aide de l'argument locales :

var bigint = 123456789123456789n;

// En allemand, on utilise les points pour séparer
// les milliers
console.log(bigint.toLocaleString("de-DE"));
// 123.456.789.123.456.789

// La plupart des pays arabes utilise
// des chiffres hindoux-arabes
console.log(bigint.toLocaleString("ar-EG"));
// ١٢٣٬٤٥٦٬٧٨٩٬١٢٣٬٤٥٦٬٧٨٩

// India utilise des séparateurs pour
// les milliers/lakh/crore
console.log(bigint.toLocaleString("en-IN"));
// 1,23,45,67,89,12,34,56,789

// La clé d'extension requiert un système de numérotation
// par exemple, le système décimal chinois
console.log(bigint.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// 一二三,四五六,七八九,一二三,四五六,七八九

// Lorsqu'on demande une langue qui peut ne pas être prise
// en charge (ici le balinais), on peut ajouter une autre
// locale qui sera utilisée en recours (ici l'indonésien)
console.log(bigint.toLocaleString(["ban", "id"]));
// 123.456.789.123.456.789

Utiliser options

Ici, on personnalise le résultat fourni par toLocaleString() grâce à l'argument options :

var bigint = 123456789123456789n;

// On utilise un format avec une devise
console.log(
  bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// 123.456.789.123.456.789,00 €

// Le yen japonais n'utilise pas de sous-unité
console.log(
  bigint.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// ￥123,456,789,123,456,789

// On limite l'écriture aux trois premiers chiffres significatifs
console.log(bigint.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// 1,23,00,00,00,00,00,00,000

Spécifications

Compatibilité des navigateurs

Voir aussi

• La propriété Intl.NumberFormat
• La méthode BigInt.prototype.toString()