Intl.NumberFormat() コンストラクター

Intl.NumberFormat() コンストラクターは、言語に依存した数値の整形ができるオブジェクトを生成します。

構文

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

引数

locales Optional

BCP 47 言語タグを持つ文字列、またはそのような文字列の配列。 locales 引数の一般的な形式と解釈については、 Intl のページを参照してください。次の Unicode 拡張キーが許可されています。

nu
使用される数値システムです。指定可能な値には "adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho" があります。
options Optional

以下のプロパティのすべてまたは一部を持つオブジェクトです。

compactDisplay
notation が "compact" の場合のみ使用されます。 "short" (既定値) または "long" のどちらかを取ります。
currency
通貨の書式で使用するための通貨です。利用可能な値は ISO 4217 通貨コードであり、例えば米ドルは "USD"、ユーロは "EUR"、日本円には "JPY" です。 — Current currency & funds code list を参照してください。既定値はありません。 style が "currency" である場合、 currency プロパティを提供する必要があります。
currencyDisplay
通貨の書式で通貨を表示する方法です。利用可能な値は次の通りです。
  • "symbol" はローカライズされた通貨記号、例えば € などを使用します。これが既定値です。
  • "narrowSymbol" は短い形式の記号を使用します ("US$100" ではなく "$100")。
  • "code" は ISO 通貨コードを使用します。
  • "name" はローカライズされた通貨名、例えば "dollar" を使用します。
currencySign
多くのロケールでは、会計の書式はマイナス記号を追加する代わりに数値を括弧で囲みます。この形式は currencySign オプションを "accounting" に設定すると有効になります。既定値は "standard" です。
localeMatcher
使用するロケール比較アルゴリズムです。使用可能な値は "lookup" および "best fit" です。既定値は "best fit" です。このオプションについての情報は、 Intl page を参照してください。
notation
数値を表示するための書式です。既定値は "standard" です。
  • "standard" は、通常の数値の書式です。
  • "scientific" は、整形された数値の次数をを返します。
  • "engineering" は、3で割ることができる場合に10のべき乗を返します。
  • "compact" は、指数表記を表す文字列で、既定値は "short" の形式を使用したものです。
numberingSystem
数値体系です。使用可能な値には、 "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", " knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", " telu", "thai", "tibt" があります。
signDisplay
数値の符号を表示するときです。既定値は "auto" です。
  • "auto" は、負の数のみ符号を表示します。
  • "never" は、符号を表示しません。
  • "always" は、常に符号を表示します。
  • "exceptZero" は正の数と負の数には符号を表示しますが、ゼロには表示しません。
style
使用する整形スタイルで、既定値は "decimal" です。
  • "decimal" は、ふつうの数値の整形に使用します。
  • "currency" は、通貨の整形に使用します。
  • "percent" は、パーセントの整形に使用します。
  • "unit" は単位の整形に使用します。
unit
The unit to use in unit formatting, Possible values are core unit identifiers, defined in UTS #35, Part 2, Section 6. A subset of units from the full list was selected for use in ECMAScript. Pairs of simple units can be concatenated with "-per-" to make a compound unit. There is no default value; if the style is "unit", the unit property must be provided.
unitDisplay
The unit formatting style to use in unit formatting, the defaults is "short".
  • "long" (e.g., 16 litres)
  • "short" (e.g., 16 l)
  • "narrow" (e.g., 16l)
useGrouping
Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators. Possible values are true and false; the default is true.

The following properties fall into two groups: minimumIntegerDigits, minimumFractionDigits, and maximumFractionDigits in one group, minimumSignificantDigits and maximumSignificantDigits in the other. If at least one property from the second group is defined, then the first group is ignored.

minimumIntegerDigits
The minimum number of integer digits to use. Possible values are from 1 to 21; the default is 1.
minimumFractionDigits
The minimum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number and percent formatting is 0; the default for currency formatting is the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information).
maximumFractionDigits
The maximum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number formatting is the larger of minimumFractionDigits and 3; the default for currency formatting is the larger of minimumFractionDigits and the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information); the default for percent formatting is the larger of minimumFractionDigits and 0.
minimumSignificantDigits
The minimum number of significant digits to use. Possible values are from 1 to 21; the default is 1.
maximumSignificantDigits
The maximum number of significant digits to use. Possible values are from 1 to 21; the default is 21.

基本的な使用

特定のロケールなしで使用すると、既定のロケール、既定のオプションで整形された文字列が返されます。

let amount = 3500;

console.log(new Intl.NumberFormat().format(amount));
// → '3,500' if in US English locale

十進数とパーセントの整形

let amount = 3500;

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

単位の整形

style'unit' である場合、 unit プロパティを提供する必要があります。オプションで、 unitDisplay が単位の整形を制御します。

let amount = 3500;

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

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

通貨の整形

style'currency' であった場合、 currency プロパティを提供する必要があります。オプションで、 currencyDisplay および currencySign が単位の整形を制御します。

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

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

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

科学、工学、短縮表記

科学の短縮表記は notation オプションで表すことができ、以下のようになります。

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

符号の表示

正の数と負の数に符号を表示し、ゼロには表示しない場合は次のようにします。

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

なお、通貨の符号が "accounting" である場合、負号の代わりに括弧が使用されることがあります。

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

// → '($3,500.00)'

仕様書

ブラウザーの互換性

BCD tables only load in the browser

関連情報