`Intl.NumberFormat`

Sie kennen möglicherweise bereits die Intl.NumberFormat-API, da sie seit einiger Zeit in modernen Umgebungen unterstützt wird.

In ihrer grundlegendsten Form ermöglicht Intl.NumberFormat das Erstellen einer wiederverwendbaren Formatierer-Instanz, die lokalisationsspezifische Zahlenformatierung unterstützt. Genau wie andere Intl.*Format-APIs unterstützt eine Formatierer-Instanz sowohl eine format- als auch eine formatToParts-Methode:

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' }
// → ]

Hinweis: Obwohl ein Großteil der Intl.NumberFormat-Funktionalität mit Number.prototype.toLocaleString erreicht werden kann, ist Intl.NumberFormat oft die bessere Wahl, da es die Erstellung einer wiederverwendbaren Formatierer-Instanz ermöglicht, die in der Regel effizienter ist.

Kürzlich hat die Intl.NumberFormat-API einige neue Funktionen hinzugewonnen.

Unterstützung für BigInt

Neben Numbers kann Intl.NumberFormat jetzt auch BigInts formatieren:

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' }
// → ]

Maßeinheiten

Intl.NumberFormat unterstützt derzeit die folgenden sogenannten einfachen Einheiten:

• Winkel: degree
• Fläche: acre, hectare
• Konzentration: percent
• Digital: bit, byte, kilobit, kilobyte, megabit, megabyte, gigabit, gigabyte, terabit, terabyte, petabyte
• Dauer: millisecond, second, minute, hour, day, week, month, year
• Länge: millimeter, centimeter, meter, kilometer, inch, foot, yard, mile, mile-scandinavian
• Masse: gram, kilogram, ounce, pound, stone
• Temperatur: celsius, fahrenheit
• Volumen: liter, milliliter, gallon, fluid-ounce

Um Zahlen mit lokalisierten Einheiten zu formatieren, verwenden Sie die Optionen style und 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'

Beachten Sie, dass im Laufe der Zeit die Unterstützung für weitere Einheiten hinzugefügt werden kann. Bitte beziehen Sie sich auf die Spezifikation für die neueste aktualisierte Liste.

Die oben genannten einfachen Einheiten können in beliebigen Zähler- und Nennerpaaren kombiniert werden, um zusammengesetzte Einheiten wie „Liter pro Acre“ oder „Meter pro Sekunde“ auszudrücken:

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

Kompakte, wissenschaftliche und technische Notation

Kompakte Notation verwendet lokalisationsspezifische Symbole, um große Zahlen darzustellen. Es ist eine benutzerfreundlichere Alternative zur wissenschaftlichen Notation:

{
  // Test der Standardnotation.
  const formatter = new Intl.NumberFormat('en', {
    notation: 'standard', // Dies ist die implizite Standardeinstellung.
  });
  formatter.format(1234.56);
  // → '1,234.56'
  formatter.format(123456);
  // → '123,456'
  formatter.format(123456789);
  // → '123,456,789'
}

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

hinweis

Hinweis: Standardmäßig wird durch die kompakte Notation auf die nächste ganze Zahl gerundet, jedoch werden immer 2 signifikante Stellen beibehalten. Sie können {minimum,maximum}FractionDigits oder {minimum,maximum}SignificantDigits festlegen, um dieses Verhalten zu überschreiben.

Intl.NumberFormat kann auch Zahlen im wissenschaftlichen Format formatieren:

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

Ingenieursnotation wird ebenfalls unterstützt:

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

Vorzeichenanzeige

In bestimmten Situationen (wie z. B. der Darstellung von Differenzen) ist es hilfreich, das Vorzeichen ausdrücklich anzuzeigen, auch wenn die Zahl positiv ist. Die neue Option signDisplay ermöglicht dies:

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%'

Um das Anzeigen des Vorzeichens bei einem Wert von 0 zu verhindern, verwenden Sie 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%'
// Hinweis: -0 wird weiterhin mit Vorzeichen angezeigt, wie zu erwarten:
formatter.format(-0);
// → '-0%'

Für Währungen ermöglicht die Option currencySign das Buchhaltungsformat, das ein lokales spezifisches Format für negative Währungsbeträge ermöglicht; beispielsweise wird der Betrag in Klammern gesetzt:

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)'

Mehr Informationen

Der relevante Spezifikationsvorschlag enthält weitere Informationen und Beispiele, einschließlich einer Anleitung zur Erkennung jedes einzelnen Intl.NumberFormat-Features.