Intl.NumberFormat.prototype.formatToParts()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2019.
formatToParts() は Intl.NumberFormat インスタンスのメソッドで、 format() によって返される、書式化された文字列のそれぞれの部分を表すオブジェクトの配列を返します。これは、ロケール固有のトークンから独自の文字列を構築するのに役立ちます。
試してみましょう
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);
// 予想される結果: "["$", "654", ",", "321", ".", "99"]"
構文
formatToParts(number)
引数
返値
書式化された数値の部分を含むオブジェクトの Array です。各オブジェクトには、type と value の 2 つのプロパティがあり、それぞれ文字列が設定されています。指定された順序で value を連結すると、format() と同じ文字列になります。type は、次のいずれかになります。
literal-
書式パターンの一部である文字列。例えば
" "など。小数点区切り文字やプラス/マイナス記号などの一般的なトークンは、それぞれ独自のトークン型を持っていることに注意してください。 integer-
数値の整数部分、またはグループ化を使用している場合はその一部（
options.useGroupingで制御）。 group-
グループ区切り文字列、
","など。グループ化を使用する場合にのみ存在します (options.useGroupingで制御)。 decimal-
小数点区切り文字列。
"."など。fractionが存在する場合にのみ存在します。 fraction-
数値の小数点以下の部分。
compact-
"M"や"thousands"などのコンパクトな指数。options.notationが"compact"の場合にのみ存在します。形式 ("short"または"long") は、options.compactDisplayで制御できます。 exponentSeparator-
指数区切り文字、たとえば
"E"。options.notationが"scientific"または"engineering"の場合にのみ存在します。 exponentMinusSign-
指数マイナス記号文字列、たとえば
"-"。options.notationが"scientific"または"engineering"で、指数が負の場合にのみ表示されます。 exponentInteger-
指数部の整数値。
options.notationが"scientific"または"engineering"の場合にのみ存在します。 nan-
NaNを表す文字列、たとえば"NaN"です。これは、数値がNaNの場合にその数値自体を表す唯一のトークンです。 infinity-
Infinityまたは-Infinityを表す文字列。これには「∞」などがあります。これは、数値がInfinityまたは-Infinityの場合に、その数値自体を表す唯一のトークンです。 plusSign-
プラス記号（例:
"+"）。 minusSign-
マイナス記号（例:
"-"）。 percentSign-
パーセント記号、たとえば
"%"など。options.styleが"percent"の場合にのみ表示されます。 unit-
単位の文字列、例えば "l" または "litres" です。
options.styleが"unit"の場合にのみ存在します。形式（"short","narrow","long"）は、options.unitDisplayによって制御できます。 currency-
通貨の文字列、例えば
"$"、"€"、"Dollar"、"Euro"などです。options.styleが"currency"の場合のみ存在します。その形式 ("code","symbol","narrowSymbol","name") はoptions.currencyDisplayで制御できます。 unknown-
上記として認識されないトークン用に予約されています。ほとんどの場合、使用されることはありません。
例
formatToParts() の使用
format() メソッドは、直接操作できない、ローカライズされた不透明な文字列を出力します。
const number = 3500;
const formatter = new Intl.NumberFormat("de-DE", {
style: "currency",
currency: "EUR",
});
formatter.format(number);
// "3.500,00 €"
しかし、多くのユーザーインターフェイスでは、この文字列の書式形式をカスタマイズしたいと要望があります。 formatToParts() メソッドは、同じ情報を複数の部分に分割して出力します。
formatter.formatToParts(number);
// 返値:
[
{ type: "integer", value: "3" },
{ type: "group", value: "." },
{ type: "integer", value: "500" },
{ type: "decimal", value: "," },
{ type: "fraction", value: "00" },
{ type: "literal", value: " " },
{ type: "currency", value: "€" },
];
これで情報は個別に利用可能となり、カスタマイズされた方法で書式化して連結することができます。例えば Array.prototype.map(), アロー関数, switch 文, テンプレートリテラル, Array.prototype.join() を使用して、特定の要素に追加のマークアップを挿入することができます。
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>"
仕様書
| Specification |
|---|
| ECMAScript® 2026 Internationalization API Specification # sec-intl.numberformat.prototype.formattoparts |