最新の環境では既にしばらくの間サポートされているため、Intl.NumberFormat API には既に精通しているかもしれません。

• Chrome: バージョン 24 からサポート
• Firefox: バージョン 29 からサポート
• Safari: バージョン 10 からサポート
• Node.js: バージョン 0.12 からサポート
• Babel: サポート済み

最も基本的な形式では、Intl.NumberFormat を使用すると、ロケール対応の数字フォーマットをサポートする再利用可能なフォーマッターインスタンスを作成できます。他の Intl.*Format API と同様に、フォーマッターインスタンスは format メソッドと formatToParts メソッドの両方をサポートしています。

const formatter = new Intl.NumberFormat('en');
formatter.format(987654.321);
// → '987,654.321'
formatter.formatToParts(987654.321);
// → [
// →   { type: 'integer', value: '987' },
// →   { type: 'group', value: ',' },
// →   { type: 'integer', value: '654' },
// →   { type: 'decimal', value: '.' },
// →   { type: 'fraction', value: '321' }
// → ]

注: Intl.NumberFormat の機能の多くは Number.prototype.toLocaleString を使用して実現できますが、Intl.NumberFormat は再利用可能なフォーマッターインスタンスを作成できるため、多くの場合、より効率的 な選択肢となります。

最近、Intl.NumberFormat API にいくつかの新しい機能が追加されました。

BigInt のサポート #

Number に加えて、Intl.NumberFormat は BigInt もフォーマットできるようになりました。

const formatter = new Intl.NumberFormat('fr');
formatter.format(12345678901234567890n);
// → '12 345 678 901 234 567 890'
formatter.formatToParts(123456n);
// → [
// →   { type: 'integer', value: '123' },
// →   { type: 'group', value: ' ' },
// →   { type: 'integer', value: '456' }
// → ]

• Chrome: バージョン 76 からサポート
• Firefox: サポートされていません
• Safari: サポートされていません
• Node.js: サポートされていません
• Babel: サポートされていません

測定単位 #

Intl.NumberFormat は、現在、以下のいわゆる *単純な単位* をサポートしています。

• 角度: degree (度)
• 面積: acre (エーカー), hectare (ヘクタール)
• 濃度: percent (パーセント)
• デジタル: bit (ビット), byte (バイト), kilobit (キロビット), kilobyte (キロバイト), megabit (メガビット), megabyte (メガバイト), gigabit (ギガビット), gigabyte (ギガバイト), terabit (テラビット), terabyte (テラバイト), petabyte (ペタバイト)
• 期間: millisecond (ミリ秒), second (秒), minute (分), hour (時間), day (日), week (週), month (月), year (年)
• 長さ: millimeter (ミリメートル), centimeter (センチメートル), meter (メートル), kilometer (キロメートル), inch (インチ), foot (フィート), yard (ヤード), mile (マイル), mile-scandinavian (スカンジナビアマイル)
• 質量: gram (グラム), kilogram (キログラム), ounce (オンス), pound (ポンド), stone (ストーン)
• 温度: celsius (摂氏), fahrenheit (華氏)
• 体積: liter (リットル), milliliter (ミリリットル), gallon (ガロン), fluid-ounce (液量オンス)

ローカライズされた単位で数値をフォーマットするには、style オプションと unit オプションを使用します。

const formatter = new Intl.NumberFormat('en', {
  style: 'unit',
  unit: 'kilobyte',
});
formatter.format(1.234);
// → '1.234 kB'
formatter.format(123.4);
// → '123.4 kB'

時間の経過とともに、より多くの単位のサポートが追加される可能性があります。 最新のリストについては、仕様書を参照してください。

上記の単純な単位は、任意の分子と分母のペアに組み合わせて、「リットル/エーカー」や「メートル/秒」などの複合単位を表すことができます。

const formatter = new Intl.NumberFormat('en', {
  style: 'unit',
  unit: 'meter-per-second',
});
formatter.format(299792458);
// → '299,792,458 m/s'

• Chrome: バージョン 77 からサポート
• Firefox: サポートされていません
• Safari: サポートされていません
• Node.js: サポートされていません
• Babel: サポートされていません

コンパクト表記、科学表記、工学表記 #

*コンパクト表記* は、ロケール固有の記号を使用して大きな数を表します。科学表記法よりも人間に優しい代替手段です。

{
  // Test standard notation.
  const formatter = new Intl.NumberFormat('en', {
    notation: 'standard', // This is the implied default.
  });
  formatter.format(1234.56);
  // → '1,234.56'
  formatter.format(123456);
  // → '123,456'
  formatter.format(123456789);
  // → '123,456,789'
}

{
  // Test compact notation.
  const formatter = new Intl.NumberFormat('en', {
    notation: 'compact',
  });
  formatter.format(1234.56);
  // → '1.2K'
  formatter.format(123456);
  // → '123K'
  formatter.format(123456789);
  // → '123M'
}

Intl.NumberFormat は、科学表記法で数値をフォーマットすることもできます。

const formatter = new Intl.NumberFormat('en', {
  style: 'unit',
  unit: 'meter-per-second',
  notation: 'scientific',
});
formatter.format(299792458);
// → '2.998E8 m/s'

工学表記もサポートされています。

const formatter = new Intl.NumberFormat('en', {
  style: 'unit',
  unit: 'meter-per-second',
  notation: 'engineering',
});
formatter.format(299792458);
// → '299.792E6 m/s'

• Chrome: バージョン 77 からサポート
• Firefox: サポートされていません
• Safari: サポートされていません
• Node.js: サポートされていません
• Babel: サポートされていません

符号の表示 #

特定の状況（デルタの表示など）では、数値が正の場合でも符号を明示的に表示すると役立ちます。新しい signDisplay オプションでこれが可能になります。

const formatter = new Intl.NumberFormat('en', {
  style: 'unit',
  unit: 'percent',
  signDisplay: 'always',
});
formatter.format(-12.34);
// → '-12.34%'
formatter.format(12.34);
// → '+12.34%'
formatter.format(0);
// → '+0%'
formatter.format(-0);
// → '-0%'

値が 0 のときに符号が表示されないようにするには、signDisplay: 'exceptZero' を使用します。

const formatter = new Intl.NumberFormat('en', {
  style: 'unit',
  unit: 'percent',
  signDisplay: 'exceptZero',
});
formatter.format(-12.34);
// → '-12.34%'
formatter.format(12.34);
// → '+12.34%'
formatter.format(0);
// → '0%'
// Note: -0 still displays with a sign, as you’d expect:
formatter.format(-0);
// → '-0%'

通貨の場合、`currencySign` オプションは *会計フォーマット* を有効にします。これは、負の通貨金額に対してロケール固有のフォーマットを有効にします。たとえば、金額を括弧で囲みます。

const formatter = new Intl.NumberFormat('en', {
  style: 'currency',
  currency: 'USD',
  signDisplay: 'exceptZero',
  currencySign: 'accounting',
});
formatter.format(-12.34);
// → '($12.34)'
formatter.format(12.34);
// → '+$12.34'
formatter.format(0);
// → '$0.00'
formatter.format(-0);
// → '($0.00)'

• Chrome: バージョン 77 からサポート
• Firefox: サポートされていません
• Safari: サポートされていません
• Node.js: サポートされていません
• Babel: サポートされていません

詳細情報 #

関連する 仕様書提案 には、個々の Intl.NumberFormat 機能を検出する方法のガイダンスなど、詳細な情報と例が記載されています。