The formatToParts() method of Intl.NumberFormat instances returns an array of objects representing each part of the formatted string that would be returned by Intl/NumberFormat/format. It is useful for building custom strings from the locale-specific tokens.
JavaScript Demo: Intl.NumberFormat.prototype.formatToParts()
const amount = 654321.987;
const options = { style: "currency", currency: "USD" };
const numberFormat = new Intl.NumberFormat("en-US", options);
const parts = numberFormat.formatToParts(amount);
const partValues = parts.map((p) => p.value);
console.log(partValues);
// Expected output: Array ["$", "654", ",", "321", ".", "99"]
Syntax
formatToParts(number)
Parameters
number- : A Number, BigInt, or string, to format. Strings are parsed in the same way as in number conversion, except that
formatToParts()will use the exact value that the string represents, avoiding loss of precision during implicit conversion to a number.
- : A Number, BigInt, or string, to format. Strings are parsed in the same way as in number conversion, except that
Return value
An Array of objects containing the formatted number in parts. Each object has two properties, type and value, each containing a string. The string concatenation of value, in the order provided, will result in the same string as Intl/NumberFormat/format. The type may be one of the following:
literal- : Any string that's a part of the format pattern; for example
" ". Note that common tokens like the decimal separator or the plus/minus signs have their own token types.
- : Any string that's a part of the format pattern; for example
integer- : The integral part of the number, or a segment of it if using grouping (controlled by
options.useGrouping).
- : The integral part of the number, or a segment of it if using grouping (controlled by
group- : The group separator string, such as
",". Only present when using grouping (controlled byoptions.useGrouping).
- : The group separator string, such as
decimal- : The decimal separator string, such as
".". Only present whenfractionis present.
- : The decimal separator string, such as
fraction- : The fractional part of the number.
compact- : The compact exponent, such as
"M"or"thousands". Only present whenoptions.notationis"compact". The form ("short"or"long") can be controlled viaoptions.compactDisplay.
- : The compact exponent, such as
exponentSeparator- : The exponent separator, such as
"E". Only present whenoptions.notationis"scientific"or"engineering".
- : The exponent separator, such as
exponentMinusSign- : The exponent minus sign string, such as
"-". Only present whenoptions.notationis"scientific"or"engineering"and the exponent is negative.
- : The exponent minus sign string, such as
exponentInteger- : The exponent's integer value. Only present when
options.notationis"scientific"or"engineering".
- : The exponent's integer value. Only present when
nan- : A string representing NaN, such as
"NaN". This is the sole token representing the number itself when the number isNaN.
- : A string representing NaN, such as
infinity- : A string representing Infinity or
-Infinity, such as"∞". This is the sole token representing the number itself when the number isInfinityor-Infinity.
- : A string representing Infinity or
plusSign- : The plus sign, such as
"+".
- : The plus sign, such as
minusSign- : The minus sign, such as
"-".
- : The minus sign, such as
percentSign- : The percent sign, such as
"%". Only present whenoptions.styleis"percent".
- : The percent sign, such as
unit- : The unit string, such as
"l"or"litres". Only present whenoptions.styleis"unit". The form ("short","narrow", or"long") can be controlled viaoptions.unitDisplay.
- : The unit string, such as
currency- : The currency string, such as
"$","€","Dollar", or"Euro". Only present whenoptions.styleis"currency". The form ("code","symbol","narrowSymbol", or"name") can be controlled viaoptions.currencyDisplay.
- : The currency string, such as
unknown- : Reserved for any token that's not recognized as one of the above; should be rarely encountered.
Examples
Using formatToParts()
The format() method outputs localized, opaque strings that cannot be manipulated directly:
const number = 3500;
const formatter = new Intl.NumberFormat("de-DE", {
style: "currency",
currency: "EUR",
});
formatter.format(number);
// "3.500,00 €"
However, in many user interfaces you may want to customize the formatting of this string, or interleave it with other texts. The formatToParts() method produces the same information in parts:
formatter.formatToParts(number);
// return value:
[
{ type: "integer", value: "3" },
{ type: "group", value: "." },
{ type: "integer", value: "500" },
{ type: "decimal", value: "," },
{ type: "fraction", value: "00" },
{ type: "literal", value: " " },
{ type: "currency", value: "€" },
];
Now the information is available separately and it can be formatted and concatenated again in a customized way. For example by using Array.prototype.map(), arrow functions, a switch statement, template literals, and Array.prototype.join(), to insert additional markup for certain components.
const numberString = formatter
.formatToParts(number)
.map(({ type, value }) => {
switch (type) {
case "currency":
return `<strong>${value}</strong>`;
default:
return value;
}
})
.join("");
console.log(numberString);
// "3.500,00 <strong>€</strong>"
Specifications
Browser compatibility
See also
- Intl.NumberFormat
- Intl/NumberFormat/format
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
