Intl.NumberFormat : méthode format()

Exemple interactif

const amount = 654321.987;

const options1 = { style: "currency", currency: "RUB" };
const numberFormat1 = new Intl.NumberFormat("ru-RU", options1);

console.log(numberFormat1.format(amount));
// Résultat attendu : "654 321,99 ₽"

const options2 = { style: "currency", currency: "USD" };
const numberFormat2 = new Intl.NumberFormat("en-US", options2);

console.log(numberFormat2.format(amount));
// Résultat attendu : "$654,321.99"

Syntaxe

format(number)

Paramètres

number

Un nombre (Number), grand entier (BigInt), ou chaîne de caractères, à formater. Les chaînes de caractères sont analysées de la même manière que dans la conversion de nombre, sauf que format() utilisera la valeur exacte que représente la chaîne de caractères, évitant ainsi toute perte de précision lors de la conversion implicite en nombre.

Valeur de retour

Une chaîne de caractères représentant le number donné, formaté selon la locale et les options de format de cet objet Intl.NumberFormat.

Description

Les valeurs Number en JavaScript souffrent d'une perte de précision si elles sont trop grandes ou trop petites, rendant la représentation textuelle inexacte. Si vous effectuez des calculs avec des entiers supérieurs à Number.MAX_SAFE_INTEGER, vous devriez utiliser un BigInt à la place, ce qui sera formaté correctement :

new Intl.NumberFormat("en-US").format(1234567891234567891); // 1,234,567,891,234,568,000
new Intl.NumberFormat("en-US").format(1234567891234567891n); // 1,234,567,891,234,567,891

Vous pouvez également passer de très grandes chaînes de caractères pour les formater en tant que chaîne décimale à précision arbitraire (si vous effectuez des calculs sur les données, vous devrez toujours travailler avec BigInt) :

new Intl.NumberFormat("en-US").format("1234567891234567891"); // 1,234,567,891,234,567,891

Exemples

Utiliser la méthode format()

Utilisez la fonction d'accesseur format pour formater une seule valeur monétaire. Le code ci-dessous montre comment formater la devise rouble pour une locale russe :

const options = { style: "currency", currency: "RUB" };
const numberFormat = new Intl.NumberFormat("ru-RU", options);
console.log(numberFormat.format(654321.987));
// "654 321,99 ₽"

Utiliser la méthode format() avec map()

Utilisez la fonction d'accesseur format pour formater tous les nombres d'un tableau. Notez que la fonction est liée à l'objet Intl.NumberFormat dont elle provient, elle peut donc être passée directement à Array.prototype.map. Ceci est considéré comme un artefact historique, faisant partie d'une convention qui n'est plus suivie pour les nouvelles fonctionnalités, mais est conservée pour maintenir la compatibilité avec les programmes existants.

const a = [123456.789, 987654.321, 456789.123];
const numberFormat = new Intl.NumberFormat("es-ES");
const formatted = a.map((n) => numberFormat.format(n));
console.log(formatted.join("; "));
// "123.456,789; 987.654,321; 456.789,123"

Utiliser la méthode format() avec une chaîne de caractères

En utilisant une chaîne de caractères, nous pouvons définir des nombres supérieurs à Number.MAX_SAFE_INTEGER sans perdre de précision.

const formatNombre = new Intl.NumberFormat("en-US");

// Ici, la valeur est convertie en Number
console.log(formatNombre.format(987654321987654321));
// 987,654,321,987,654,300

// Ici, nous utilisons une chaîne de caractères et ne perdons pas de précision
console.log(formatNombre.format("987654321987654321"));
// 987,654,321,987,654,321

Nous pouvons également utiliser la syntaxe générale de l'exposant « E » pour les chaînes de caractères décimales : #.#E#. Le code ci-dessous crée un BigInt, le convertit en chaîne de caractères avec le suffixe E-6, puis le formate.

const formatNombre = new Intl.NumberFormat("en-US");
const grandNombre = 1000000000000000110000n;
console.log(formatNombre.format(grandNombre));
// "1,000,000,000,000,000,110,000"

// Formater en tant que chaîne de caractères utilisant la syntaxe `E` :
console.log(formatNombre.format(`${grandNombre}E-6`));
// "1,000,000,000,000,000.11"

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet Intl.NumberFormat
• La méthode Number.prototype.toLocaleString()