Constructeur Intl.NumberFormat()

Exemple interactif

const number = 123456.789;

console.log(
  new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(
    number,
  ),
);
// Résultat attendu : "123.456,79 €"

// Le yen japonais n'utilise pas d'unité mineure
console.log(
  new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" }).format(
    number,
  ),
);
// Résultat attendu : "￥123,457"

// Limiter à trois chiffres significatifs
console.log(
  new Intl.NumberFormat("en-IN", { maximumSignificantDigits: 3 }).format(
    number,
  ),
);
// Résultat attendu : "1,23,000"

Syntaxe

new Intl.NumberFormat()
new Intl.NumberFormat(locales)
new Intl.NumberFormat(locales, options)

Intl.NumberFormat()
Intl.NumberFormat(locales)
Intl.NumberFormat(locales, options)

Paramètres

locales Facultatif

Une chaîne de caractères avec une balise de langue BCP 47 ou une instance de Intl.Locale, ou un tableau de tels identifiants de locale. La locale par défaut de l'environnement d'exécution est utilisée lorsque undefined est passé ou lorsqu'aucun des identifiants de locale définis n'est pris en charge. Pour la forme générale et l'interprétation de l'argument locales, voir la description du paramètre sur la page principale de Intl.

La clé d'extension Unicode suivante est autorisée :

nu

Voir numberingSystem.

Cette clé peut également être définie avec options (comme indiqué ci-dessous). Lorsque les deux sont définis, la propriété options prend le pas.

options Facultatif

Un objet. Pour faciliter la lecture, la liste des propriétés est divisée en sections en fonction de leur objectif, y compris options de locale, options de style, options de chiffres et autres options.

Options de locale

localeMatcher

L'algorithme de correspondance de locale à utiliser. Les valeurs possibles sont "lookup" et "best fit" ; la valeur par défaut est "best fit". Pour plus d'informations sur cette option, voir Identification et négociation de la locale.

numberingSystem

Le système de numération à utiliser pour le formatage des nombres, tel que "arab", "hans", "mathsans", etc. Pour une liste des types de systèmes de numération pris en charge, voir Intl.supportedValuesOf() ; la valeur par défaut dépend de la locale. Cette option peut également être définie via la clé d'extension Unicode nu ; si les deux sont fournis, la propriété options prend le pas.

Options de style

En fonction du style utilisé, certaines options peuvent être ignorées et d'autres peuvent être requises :

style

Le style de formatage à utiliser.

"decimal" (par défaut)

Pour le formatage des nombres simples.

"currency"

Pour le formatage des devises.

"percent"

Pour le formatage des pourcentages.

"unit"

Pour le formatage des unités.

currency

La devise à utiliser pour le formatage des devises. Les valeurs possibles sont les codes de devise ISO 4217, tels que "USD" pour le dollar américain, "EUR" pour l'euro ou "CNY" pour le RMB chinois — voir Intl.supportedValuesOf(). Il n'y a pas de valeur par défaut ; si le style est "currency", la propriété currency doit être fournie. Elle est normalisée en majuscules.

currencyDisplay

Comment afficher la devise dans le formatage des devises.

"code"

Utiliser le code de devise ISO.

"symbol" (par défaut)

Utiliser un symbole de devise localisé, tel que €.

"narrowSymbol"

Utiliser un symbole de format étroit (« $100 » plutôt que « US$100 »).

"name"

Utiliser un nom de devise localisé, tel que "dollar".

currencySign

Dans de nombreuses locales, le format comptable signifie d'encadrer le nombre avec des parenthèses au lieu d'ajouter un signe moins. Les valeurs possibles sont "standard" et "accounting" ; la valeur par défaut est "standard".

unit

L'unité à utiliser dans le formatage des unités. Les valeurs possibles sont répertoriées dans Intl.supportedValuesOf(). Les paires d'unités simples peuvent être concaténées avec "-per-" pour créer une unité composée. Il n'y a pas de valeur par défaut ; si le style est "unit", la propriété unit doit être fournie.

unitDisplay

Le style de formatage des unités à utiliser dans le formatage des unités. Les valeurs possibles sont :

"short" (par défaut)

Par exemple, 16 l.

"narrow"

Par exemple, 16l.

"long"

Par exemple, 16 litres.

Options de chiffres

Les propriétés suivantes sont également prises en charge par Intl.PluralRules.

minimumIntegerDigits

Le nombre minimum de chiffres entiers à utiliser. Une valeur avec un nombre de chiffres entiers inférieur à ce nombre sera complétée à gauche avec des zéros (jusqu'à la longueur définie) lors du formatage. Les valeurs possibles vont de 1 à 21 ; la valeur par défaut est 1.

minimumFractionDigits

Le nombre minimum de chiffres fractionnaires à utiliser. Les valeurs possibles vont de 0 à 100 ; la valeur par défaut pour le formatage des nombres simples et des pourcentages est 0 ; la valeur par défaut pour le formatage des devises est le nombre de chiffres de l'unité mineure fourni par la liste des codes de devises ISO 4217 ^(angl.) (2 si la liste ne fournit pas cette information). Voir Valeurs par défaut des chiffres significatifs/fractionnaires pour savoir quand cette valeur par défaut est appliquée.

maximumFractionDigits

Le nombre maximum de chiffres fractionnaires à utiliser. Les valeurs possibles vont de 0 à 100 ; la valeur par défaut pour le formatage des nombres simples est le plus grand de minimumFractionDigits et 3 ; la valeur par défaut pour le formatage des devises est le plus grand de minimumFractionDigits et le nombre de chiffres de l'unité mineure fourni par la liste des codes de devises ISO 4217 ^(angl.) (2 si la liste ne fournit pas cette information) ; la valeur par défaut pour le formatage des pourcentages est le plus grand de minimumFractionDigits et 0. Voir Valeurs par défaut des chiffres significatifs/fractionnaires pour savoir quand cette valeur par défaut est appliquée.

minimumSignificantDigits

Le nombre minimum de chiffres significatifs à utiliser. Les valeurs possibles vont de 1 à 21 ; la valeur par défaut est 1. Voir Valeurs par défaut des chiffres significatifs/fractionnaires pour savoir quand cette valeur par défaut est appliquée.

maximumSignificantDigits

Le nombre maximum de chiffres significatifs à utiliser. Les valeurs possibles vont de 1 à 21 ; la valeur par défaut est 21. Voir Valeurs par défaut des chiffres significatifs/fractionnaires pour savoir quand cette valeur par défaut est appliquée.

roundingPriority

Définit comment les conflits d'arrondi seront résolus si à la fois "FractionDigits" (minimumFractionDigits/maximumFractionDigits) et "SignificantDigits" (minimumSignificantDigits/maximumSignificantDigits) sont définis. Valeurs possibles :

"auto" (par défaut)

Le résultat de la propriété des chiffres significatifs est utilisé.

"morePrecision"

Le résultat de la propriété qui donne plus de précision est utilisé.

"lessPrecision"

Le résultat de la propriété qui donne moins de précision est utilisé.

La valeur "auto" est normalisée en "morePrecision" si notation est "compact" et qu'aucune des quatre options "FractionDigits"/"SignificantDigits" n'est définie.

Notez que pour les valeurs autres que auto, le résultat avec plus de précision est calculé à partir des maximumSignificantDigits et maximumFractionDigits (les paramètres minimums de chiffres fractionnaires et significatifs sont ignorés).

roundingIncrement

Indique l'incrément auquel l'arrondi doit avoir lieu par rapport à la magnitude d'arrondi calculée. Les valeurs possibles sont 1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500 et 5000 ; la valeur par défaut est 1. Il ne peut pas être combiné avec l'arrondi des chiffres significatifs ou tout paramètre de roundingPriority autre que auto.

roundingMode

Comment les décimales doivent être arrondies. Les valeurs possibles sont :

"ceil"

Arrondir vers +∞. Les valeurs positives sont arrondies vers le haut. Les valeurs négatives sont arrondies « plus positivement ».

"floor"

Arrondir vers -∞. Les valeurs positives sont arrondies vers le bas. Les valeurs négatives sont arrondies « plus négativement ».

"expand"

Arrondir loin de 0. La magnitude de la valeur est toujours augmentée par l'arrondi. Les valeurs positives sont arrondies vers le haut. Les valeurs négatives sont arrondies « plus négativement ».

"trunc"

Arrondir vers 0. La magnitude de la valeur est toujours réduite par l'arrondi. Les valeurs positives sont arrondies vers le bas. Les valeurs négatives sont arrondies « moins négativement ».

"halfCeil"

Égalité vers +∞. Les valeurs au-dessus de la demi-incrémentation sont arrondies comme "ceil" (vers +∞), et en dessous comme "floor" (vers -∞). Sur la demi-incrémentation, les valeurs sont arrondies comme "ceil".

"halfFloor"

Égalité vers -∞. Les valeurs au-dessus de la demi-incrémentation sont arrondies comme "ceil" (vers +∞), et en dessous comme "floor" (vers -∞). Sur la demi-incrémentation, les valeurs sont arrondies comme "floor".

"halfExpand" (par défaut)

Égalité loin de 0. Les valeurs au-dessus de la demi-incrémentation sont arrondies comme "expand" (loin de zéro), et en dessous comme "trunc" (vers 0). Sur la demi-incrémentation, les valeurs sont arrondies comme "expand".

"halfTrunc"

Égalité vers 0. Les valeurs au-dessus de la demi-incrémentation sont arrondies comme "expand" (loin de zéro), et en dessous comme "trunc" (vers 0). Sur la demi-incrémentation, les valeurs sont arrondies comme "trunc".

"halfEven"

Égalité vers l'entier pair le plus proche. Les valeurs au-dessus de la demi-incrémentation sont arrondies comme "expand" (loin de zéro), et en dessous comme "trunc" (vers 0). Sur la demi-incrémentation, les valeurs sont arrondies vers le chiffre pair le plus proche.

Ces options reflètent le guide de l'utilisateur ICU ^(angl.), où "expand" et "trunc" correspondent respectivement à ICU "UP" et "DOWN". L'exemple des modes d'arrondi ci-dessous montre comment chaque mode fonctionne.

trailingZeroDisplay

La stratégie pour afficher les zéros finaux sur les nombres entiers. Les valeurs possibles sont :

"auto" (par défaut)

Conserver les zéros finaux selon minimumFractionDigits et minimumSignificantDigits.

"stripIfInteger"

Supprimer les chiffres fractionnaires s'ils sont tous nuls. C'est la même chose que "auto" si l'un des chiffres fractionnaires est non nul.

Valeurs par défaut des SignificantDigits/FractionDigits

Pour les quatre options ci-dessus (les options FractionDigits et SignificantDigits), nous avons mentionné leurs valeurs par défaut ; cependant, ces valeurs par défaut ne sont pas appliquées de manière inconditionnelle. Elles ne sont appliquées que lorsque la propriété va réellement être utilisée, ce qui dépend des paramètres roundingPriority et notation. Plus précisément :

• Si roundingPriority n'est pas "auto", alors les quatre options s'appliquent.
• Si roundingPriority est "auto" et qu'au moins une option SignificantDigits est définie, alors les options SignificantDigits s'appliquent et les options FractionDigits sont ignorées.
• Si roundingPriority est "auto", et qu'au moins une option FractionDigits est définie ou que notation n'est pas "compact", alors les options FractionDigits s'appliquent et les options SignificantDigits sont ignorées.
• Si roundingPriority est "auto", notation est "compact", et qu'aucune des quatre options n'est définie, alors elles sont définies à { minimumFractionDigits: 0, maximumFractionDigits: 0, minimumSignificantDigits: 1, maximumSignificantDigits: 2 }, indépendamment des valeurs par défaut mentionnées ci-dessus, et roundingPriority est défini à "morePrecision".

Autres options

notation

Le formatage qui doit être affiché pour le nombre. Les valeurs possibles sont :

"standard" (par défaut)

Formatage de nombre simple.

"scientific"

Retourne l'ordre de grandeur pour le nombre formaté.

"engineering"

Retourne l'exposant de dix lorsqu'il est divisible par trois.

"compact"

Une chaîne de caractères représentant l'exposant ; par défaut, utilise la forme « courte ».

compactDisplay

Utilisé uniquement lorsque notation est "compact". Les valeurs possibles sont "short" et "long" ; la valeur par défaut est "short".

useGrouping

Indique s'il faut utiliser des séparateurs de regroupement, tels que des séparateurs de milliers ou des séparateurs de « milliers/lakhs/crores ».

"always"

Affiche les séparateurs de regroupement même si la locale préfère autrement.

"auto"

Affiche les séparateurs de regroupement en fonction de la préférence de la locale, ce qui peut également dépendre de la devise.

"min2"

Affiche les séparateurs de regroupement lorsqu'il y a au moins 2 chiffres dans un groupe.

true

Même chose que "always".

false

Ne pas afficher de séparateurs de regroupement.

La valeur par défaut est "min2" si notation est "compact", et "auto" sinon. Les valeurs de chaîne de caractères "true" et "false" sont acceptées, mais sont toujours converties en la valeur par défaut.

signDisplay

Quand afficher le signe pour le nombre. Les valeurs possibles sont :

"auto" (par défaut)

Affiche le signe uniquement pour les nombres négatifs, y compris zéro négatif.

"always"

Affiche toujours le signe.

"exceptZero"

Affiche le signe pour les nombres positifs et négatifs, mais pas pour zéro.

"negative"

Affiche le signe uniquement pour les nombres négatifs, à l'exclusion du zéro négatif.

"never"

Ne jamais afficher le signe.

Valeur de retour

Un nouvel objet Intl.NumberFormat.

Normalement, Intl.NumberFormat() peut être appelé avec ou sans new, et une nouvelle instance de Intl.NumberFormat est renvoyée dans les deux cas. Cependant, si la valeur de this est un objet qui est instanceof Intl.NumberFormat (cela ne signifie pas nécessairement qu'il a été créé via new Intl.NumberFormat ; cela signifie simplement qu'il a Intl.NumberFormat.prototype dans sa chaîne de caractères de prototypes), alors la valeur de this est renvoyée à la place, avec le nouvel objet Intl.NumberFormat caché dans une propriété [Symbol(IntlLegacyConstructedSymbol)] (un symbole unique réutilisé entre les instances).

const formateur = Intl.NumberFormat.call(
  { __proto__: Intl.NumberFormat.prototype },
  "en-US",
  { notation: "scientific" },
);
console.log(Object.getOwnPropertyDescriptors(formateur));
// {
//   [Symbol(IntlLegacyConstructedSymbol)]: {
//     value: NumberFormat [Intl.NumberFormat] {},
//     writable: false,
//     enumerable: false,
//     configurable: false
//   }
// }

Notez qu'il n'y a qu'une seule instance réelle de Intl.NumberFormat ici : celle cachée dans [Symbol(IntlLegacyConstructedSymbol)]. L'appel des méthodes format() et resolvedOptions() sur formateur utiliserait correctement les options stockées dans cette instance, mais l'appel de toutes les autres méthodes (par exemple, formatRange()) échouerait avec « TypeError: formatRange method called on incompatible Object », car ces méthodes ne consultent pas les options de l'instance cachée.

Ce comportement, appelé ChainNumberFormat, ne se produit pas lorsque Intl.NumberFormat() est appelé sans new mais avec this défini sur autre chose qui n'est pas un instanceof Intl.NumberFormat. Si vous l'appelez directement comme Intl.NumberFormat(), la valeur de this est Intl, et une nouvelle instance de Intl.NumberFormat est créée normalement.

Exceptions

RangeError

Levée dans l'un des cas suivants :

• Une propriété qui prend des valeurs énumérées (comme style, units, currency, etc.) est définie sur une valeur invalide.
• Les propriétés maximumFractionDigits et minimumFractionDigits sont toutes deux définies, et elles sont définies sur des valeurs différentes. Notez qu'en fonction des différentes options de formatage, ces propriétés peuvent avoir des valeurs par défaut. Il est donc possible d'obtenir cette erreur même si vous ne définissez qu'une seule des propriétés.

TypeError

Levée si la propriété options.style est définie sur "unit" ou "currency", et qu'aucune valeur n'a été définie pour la propriété correspondante options.unit ou options.currency.

Exemples

Utilisation simple

Dans une utilisation de base sans définir de locale, une chaîne de caractères formatée dans la locale par défaut et avec les options par défaut est retournée.

const quantite = 3500;

console.log(new Intl.NumberFormat().format(quantite));
// '3,500' si la locale est l'anglais américain

Format décimal et proportionnel

const quantite = 3500;

new Intl.NumberFormat("en-US", {
  style: "decimal",
}).format(quantite); // '3,500'
new Intl.NumberFormat("en-US", {
  style: "percent",
}).format(quantite); // '350,000%'

Format des unités

Si le style est 'unit', une propriété unit doit être fournie. Optionnellement, unitDisplay contrôle le formatage de l'unité.

const quantite = 3500;

new Intl.NumberFormat("en-US", {
  style: "unit",
  unit: "liter",
}).format(quantite); // '3,500 L'

new Intl.NumberFormat("en-US", {
  style: "unit",
  unit: "liter",
  unitDisplay: "long",
}).format(quantite); // '3,500 liters'

Format des devises

Si le style est 'currency', une propriété currency doit être fournie. Optionnellement, currencyDisplay et currencySign contrôlent le formatage de l'unité.

const quantite = -3500;
new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
}).format(quantite); // '-$3,500.00'

new Intl.NumberFormat("bn", {
  style: "currency",
  currency: "USD",
  currencyDisplay: "name",
}).format(quantite); // '-3,500.00 US dollars'

new Intl.NumberFormat("bn", {
  style: "currency",
  currency: "USD",
  currencySign: "accounting",
}).format(quantite); // '($3,500.00)'

Notations scientifiques, techniques ou compactes

Les notations scientifiques et compacte sont représentées par l'option notation et peuvent être formatées comme suit :

new Intl.NumberFormat("en-US", {
  notation: "scientific",
}).format(987654321);
// 9.877E8

new Intl.NumberFormat("pt-PT", {
  notation: "scientific",
}).format(987654321);
// 9,877E8

new Intl.NumberFormat("en-GB", {
  notation: "engineering",
}).format(987654321);
// 987.654E6

new Intl.NumberFormat("de", {
  notation: "engineering",
}).format(987654321);
// 987,654E6

new Intl.NumberFormat("zh-CN", {
  notation: "compact",
}).format(987654321);
// 9.9亿

new Intl.NumberFormat("fr", {
  notation: "compact",
  compactDisplay: "long",
}).format(987654321);
// 988 millions

new Intl.NumberFormat("en-GB", {
  notation: "compact",
  compactDisplay: "short",
}).format(987654321);
// 988M

Afficher les signes

Afficher un signe pour les nombres positifs et négatifs, mais pas pour zéro :

new Intl.NumberFormat("en-US", {
  style: "percent",
  signDisplay: "exceptZero",
}).format(0.55);
// '+55%'

Notez que lorsque le signe de la devise est "accounting", des parenthèses peuvent être utilisées à la place d'un signe moins :

new Intl.NumberFormat("bn", {
  style: "currency",
  currency: "USD",
  currencySign: "accounting",
  signDisplay: "always",
}).format(-3500);
// '($3,500.00)'

FractionDigits, SignificantDigits et IntegerDigits

Vous pouvez définir le nombre minimum ou maximum de chiffres fractionnaires, entiers ou significatifs à afficher lors du formatage d'un nombre.

Utiliser FractionDigits et IntegerDigits

Les propriétés de chiffres entiers et fractionnaires indiquent le nombre de chiffres à afficher avant et après le point décimal, respectivement. Si la valeur à afficher a moins de chiffres entiers que défini, elle sera complétée à gauche avec des zéros pour atteindre le nombre attendu. Si elle a moins de chiffres fractionnaires, elle sera complétée à droite avec des zéros. Les deux cas sont illustrés ci-dessous :

// Le formatage ajoute des zéros pour afficher le nombre minimum de
// chiffres entiers et fractionnaires
console.log(
  new Intl.NumberFormat("en", {
    minimumIntegerDigits: 3,
    minimumFractionDigits: 4,
  }).format(4.33),
);
// "004.3300"

Si une valeur a plus de chiffres fractionnaires que le nombre maximum défini, elle sera arrondie. La manière dont elle est arrondie dépend de la propriété roundingMode (plus de détails sont fournis dans la section modes d'arrondi). Ci-dessous, la valeur est arrondie de cinq chiffres fractionnaires (4.33145) à deux (4.33) :

// Afficher la valeur raccourcie au nombre maximum de chiffres
console.log(
  new Intl.NumberFormat("en", {
    maximumFractionDigits: 2,
  }).format(4.33145),
);
// "4.33"

Les chiffres fractionnaires minimums n'ont aucun effet si la valeur a déjà plus de 2 chiffres fractionnaires :

// Les fractions minimums n'ont aucun effet si la valeur a une précision
// plus élevée.
console.log(
  new Intl.NumberFormat("en", {
    minimumFractionDigits: 2,
  }).format(4.33145),
);
// "4.331"

La valeur formatée ci-dessus est arrondie à 3 chiffres, même si nous n'avons pas défini le nombre maximum de chiffres ! Ceci est dû au fait qu'une valeur par défaut de maximumFractionDigits est définie lorsque nous spécifions minimumFractionDigits, et vice versa. Les valeurs par défaut de maximumFractionDigits et minimumFractionDigits sont respectivement 3 et 0.

Vous pouvez utiliser resolvedOptions() pour inspecter le formateur.

console.log(
  new Intl.NumberFormat("en", {
    maximumFractionDigits: 2,
  }).resolvedOptions(),
);
// {
//   …
//   minimumIntegerDigits: 1,
//   minimumFractionDigits: 0,
//   maximumFractionDigits: 2,
//   …
// }

console.log(
  new Intl.NumberFormat("en", {
    minimumFractionDigits: 2,
  }).resolvedOptions(),
);
// {
//   …
//   minimumIntegerDigits: 1,
//   minimumFractionDigits: 2,
//   maximumFractionDigits: 3,
//   …
// }

Utiliser SignificantDigits

Le nombre de chiffres significatifs est le nombre total de chiffres, y compris les parties entières et fractionnaires. La propriété maximumSignificantDigits est utilisée pour indiquer le nombre total de chiffres de la valeur d'origine à afficher.

Les exemples ci-dessous montrent comment cela fonctionne. Notez en particulier le dernier cas : seul le premier chiffre est conservé et les autres sont supprimés/mis à zéro.

// Afficher 5 chiffres significatifs
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 5,
  }).format(54.33145),
);
// "54.331"

// Afficher 2 chiffres significatifs
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(54.33145),
);
// "54"

// Afficher 1 chiffre significatif
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 1,
  }).format(54.33145),
);
// "50"

La propriété minimumSignificantDigits garantit qu'au moins le nombre défini de chiffres est affiché, en ajoutant des zéros à la fin de la valeur si nécessaire.

// Minimum 10 chiffres significatifs
console.log(
  new Intl.NumberFormat("en", {
    minimumSignificantDigits: 10,
  }).format(54.33145),
);
// "54.33145000"

Définir les chiffres significatifs et fractionnaires en même temps

Les chiffres fractionnaires (minimumFractionDigits/maximumFractionDigits) et les chiffres significatifs (minimumSignificantDigits/maximumSignificantDigits) sont deux façons de contrôler combien de chiffres fractionnaires et principaux doivent être formatés. Si les deux sont utilisés en même temps, il est possible qu'ils entrent en conflit.

Ces conflits sont résolus en utilisant la propriété roundingPriority. Par défaut, cette propriété a la valeur "auto", ce qui signifie que si l'une des propriétés minimumSignificantDigits ou maximumSignificantDigits est définie, les propriétés de chiffres fractionnaires et entiers seront ignorées.

Par exemple, le code ci-dessous formate la valeur de 4.33145 avec maximumFractionDigits: 3, puis maximumSignificantDigits: 2, et enfin les deux. La valeur avec les deux propriétés est celle définie par maximumSignificantDigits.

console.log(
  new Intl.NumberFormat("en", {
    maximumFractionDigits: 3,
  }).format(4.33145),
);
// "4.331"
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(4.33145),
);
// "4.3"
console.log(
  new Intl.NumberFormat("en", {
    maximumFractionDigits: 3,
    maximumSignificantDigits: 2,
  }).format(4.33145),
);
// "4.3"

En utilisant resolvedOptions() pour inspecter le formateur, nous pouvons voir que l'objet retourné n'inclut pas maximumFractionDigits lorsque maximumSignificantDigits ou minimumSignificantDigits sont définis.

console.log(
  new Intl.NumberFormat("en", {
    maximumFractionDigits: 3,
    maximumSignificantDigits: 2,
  }).resolvedOptions(),
);
// {
//   …
//   minimumIntegerDigits: 1,
//   minimumSignificantDigits: 1,
//   maximumSignificantDigits: 2,
//   …
// }
console.log(
  new Intl.NumberFormat("en", {
    maximumFractionDigits: 3,
    minimumSignificantDigits: 2,
  }).resolvedOptions(),
);
// {
//   …
//   minimumIntegerDigits: 1,
//   minimumSignificantDigits: 2,
//   maximumSignificantDigits: 21,
//   …
// }

En plus de "auto", vous pouvez résoudre les conflits en définissant roundingPriority comme "morePrecision" ou "lessPrecision". Le formateur calcule la précision en utilisant les valeurs de maximumSignificantDigits et maximumFractionDigits.

Le code ci-dessous montre le format sélectionné pour les trois priorités d'arrondi différentes :

const maxFracNF = new Intl.NumberFormat("en", {
  maximumFractionDigits: 3,
});
console.log(`maximumFractionDigits:3 - ${maxFracNF.format(1.23456)}`);
// "maximumFractionDigits:2 - 1.235"

const maxSigNS = new Intl.NumberFormat("en", {
  maximumSignificantDigits: 3,
});
console.log(`maximumSignificantDigits:3 - ${maxSigNS.format(1.23456)}`);
// "maximumSignificantDigits:3 - 1.23"

const bothAuto = new Intl.NumberFormat("en", {
  maximumSignificantDigits: 3,
  maximumFractionDigits: 3,
});
console.log(`auto - ${bothAuto.format(1.23456)}`);
// "auto - 1.23"

const bothLess = new Intl.NumberFormat("en", {
  roundingPriority: "lessPrecision",
  maximumSignificantDigits: 3,
  maximumFractionDigits: 3,
});
console.log(`lessPrecision - ${bothLess.format(1.23456)}`);
// "lessPrecision - 1.23"

const bothMore = new Intl.NumberFormat("en", {
  roundingPriority: "morePrecision",
  maximumSignificantDigits: 3,
  maximumFractionDigits: 3,
});
console.log(`morePrecision - ${bothMore.format(1.23456)}`);
// "morePrecision - 1.235"

Notez que l'algorithme peut se comporter de manière contre-intuitive si une valeur minimale est définie sans valeur maximale. L'exemple ci-dessous formate la valeur 1 en définissant minimumFractionDigits: 2 (formatage en 1.00) et minimumSignificantDigits: 2 (formatage en 1.0). Puisque 1.00 a plus de chiffres que 1.0, cela devrait être le résultat lors de la priorité morePrecision, mais en fait, c'est le contraire qui se produit :

const bothLess = new Intl.NumberFormat("en", {
  roundingPriority: "lessPrecision",
  minimumFractionDigits: 2,
  minimumSignificantDigits: 2,
});
console.log(`lessPrecision - ${bothLess.format(1)}`);
// "lessPrecision - 1.00"

const bothMore = new Intl.NumberFormat("en", {
  roundingPriority: "morePrecision",
  minimumFractionDigits: 2,
  minimumSignificantDigits: 2,
});
console.log(`morePrecision - ${bothMore.format(1)}`);
// "morePrecision - 1.0"

La raison en est que seules les valeurs de « précision maximale » sont utilisées pour le calcul, et la valeur par défaut de maximumSignificantDigits est beaucoup plus élevée que celle de maximumFractionDigits.

Modes d'arrondi

Si une valeur a plus de chiffres fractionnaires que ceux autorisés par les options du constructeur, la valeur formatée sera arrondie au nombre défini de chiffres fractionnaires. La manière dont la valeur est arrondie dépend de la propriété roundingMode.

Les formateurs de nombres utilisent par défaut l'arrondi halfExpand, qui arrondit les valeurs « à l'écart de zéro " au demi-incrément (en d'autres termes, la magnitude de la valeur est arrondie vers le haut).

Pour un nombre positif, si les chiffres fractionnaires à supprimer sont plus proches de l'incrément suivant (ou au point médian), les chiffres fractionnaires restants seront arrondis vers le haut, sinon ils seront arrondis vers le bas. Cela est illustré ci-dessous : 2,23 arrondi à deux chiffres significatifs est tronqué à 2,2 car 2,23 est inférieur au demi-incrément 2,25, tandis que les valeurs de 2,25 et plus sont arrondies à 2,3 :

// Valeur inférieure au demi-incrément : arrondir vers le bas.
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(2.23),
);
// "2.2"

// Valeur au point médian ou au-dessus : arrondir vers le haut.
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(2.25),
);
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(2.28),
);
// "2.3"
// "2.3"

Un nombre négatif au point médian ou en dessous est également arrondi à l'écart de zéro (devient plus négatif) :

// Valeur inférieure au demi-incrément : arrondir vers le bas.
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(-2.23),
);
// "-2.2"

// Valeur au point médian ou au-dessus : arrondir vers le haut.
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(-2.25),
);
console.log(
  new Intl.NumberFormat("en", {
    maximumSignificantDigits: 2,
  }).format(-2.28),
);
// "-2.3"
// "-2.3"

Le tableau ci-dessous montre l'effet des différents modes d'arrondi pour les valeurs positives et négatives qui se trouvent sur et autour du demi-incrément.

Lorsque vous utilisez halfEven, son comportement dépend également de la parité (impair ou pair) du dernier chiffre du nombre arrondi. Par exemple, le comportement de halfEven dans le tableau ci-dessus est le même que celui de halfTrunc, car les magnitudes de tous les nombres se situent entre un plus petit nombre « pair » (2.2) et un plus grand nombre « impair » (2.3). Si les nombres se situent entre ±2.3 et ±2.4, halfEven se comportera plutôt comme halfExpand. Ce comportement évite de sous-estimer ou de surestimer systématiquement les demi-incréments dans un grand échantillon de données.

Utiliser roundingIncrement

Parfois, nous voulons arrondir les chiffres fractionnaires restants à un autre incrément que l'entier suivant. Par exemple, les devises pour lesquelles la plus petite pièce est de 5 cents peuvent vouloir arrondir la valeur à des incréments de 5, reflétant les montants qui peuvent réellement être payés en espèces.

Ce type d'arrondi peut être réalisé avec la propriété roundingIncrement.

Par exemple, si maximumFractionDigits est 2 et roundingIncrement est 5, alors le nombre est arrondi au 0,05 le plus proche :

const nf = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 2,
  roundingIncrement: 5,
});

console.log(nf.format(11.29)); // "$11.30"
console.log(nf.format(11.25)); // "$11.25"
console.log(nf.format(11.22)); // "$11.20"

Ce modèle particulier est appelé « arrondi au nickel », où nickel est le nom familier pour une pièce de 5 cents aux États-Unis. Pour arrondir au dixième de dollar le plus proche (« arrondi à la dime »), vous pouvez changer roundingIncrement à 10.

const nf = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 2,
  roundingIncrement: 10,
});

console.log(nf.format(11.29)); // "$11.30"
console.log(nf.format(11.25)); // "$11.30"
console.log(nf.format(11.22)); // "$11.20"

Vous pouvez également utiliser roundingMode pour changer l'algorithme d'arrondi. L'exemple ci-dessous montre comment l'arrondi halfCeil peut être utilisé pour arrondir la valeur « moins positive » en dessous de l'incrément d'arrondi à moitié et « plus positive » si elle est au-dessus ou sur l'incrément à moitié. Le chiffre incrémenté est « 0,05 », donc l'incrément à moitié est à 0,025 (ci-dessous, cela est montré à 11,225).

const nf = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 2,
  roundingIncrement: 5,
  roundingMode: "halfCeil",
});

console.log(nf.format(11.21)); // "$11.20"
console.log(nf.format(11.22)); // "$11.20"
console.log(nf.format(11.224)); // "$11.20"
console.log(nf.format(11.225)); // "$11.25"
console.log(nf.format(11.23)); // "$11.25"

Si vous devez changer le nombre de chiffres, rappelez-vous que minimumFractionDigits et maximumFractionDigits doivent tous deux être définis sur la même valeur, sinon une RangeError est levée.

roundingIncrement ne peut pas être combiné avec l'arrondi des chiffres significatifs ou toute autre configuration de roundingPriority autre que auto.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet Intl.NumberFormat
• La méthode Intl.supportedValuesOf()
• L'objet Intl