Signatur
Beschreibung
Intl.NumberFormat ist Teil der ECMAScript Internationalization API und ermöglicht es, Zahlen entsprechend der Konventionen einer bestimmten Sprache oder Region zu formatieren. Das umfasst Tausendertrennzeichen, Dezimaltrennzeichen, Währungssymbole, Prozentzeichen sowie physikalische Einheiten wie Kilometer oder Megabyte.
Ein Intl.NumberFormat-Objekt wird einmal mit einem Locale (z. B. "de-DE" für Deutsch/Deutschland) und einem Optionsobjekt erstellt. Die eigentliche Formatierung erfolgt anschließend über die Methode format(). Werden viele Zahlen mit denselben Optionen formatiert, ist es effizienter, das Objekt zu cachen, anstatt es jedes Mal neu zu erzeugen.
Typische Anwendungsfälle sind:
- Anzeige von Preisen in einer bestimmten Währung (
style: "currency") - Darstellung von Prozentwerten (
style: "percent") - Formatierung von Messwerten mit SI-Einheiten (
style: "unit") - Kompakte Darstellung großer Zahlen (
notation: "compact") - Wissenschaftliche oder technische Notation (
notation: "scientific"/"engineering")
Die Klasse bietet außerdem formatToParts(), um die einzelnen Bestandteile eines formatierten Ausdrucks (z. B. Ganzzahl, Dezimaltrenner, Bruchanteil, Währungssymbol) als Array von Objekten zu erhalten — nützlich für individuelle Styling-Anforderungen im UI.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Systemsprache des Browsers/Laufzeit | Ein BCP-47-Sprach-Tag (z. B. "de-DE", "en-US", "ja-JP") oder ein Array solcher Tags. Bestimmt die Formatierungskonventionen (Trennzeichen, Symbole usw.). |
| $options | object | {} | Optionales Konfigurationsobjekt mit folgenden häufig genutzten Feldern:
|
Rückgabewert
Intl.NumberFormat-Instanz, die zur Formatierung von Zahlen verwendet werden kann.Beispiele
Einfache Zahlen- und Währungsformatierung
// Dezimalzahl auf Deutsch
const dezimal = new Intl.NumberFormat("de-DE");
console.log(dezimal.format(1234567.89));
// → "1.234.567,89"
// Preis in Euro (Deutschland)
const euro = new Intl.NumberFormat("de-DE", {
style: "currency",
currency: "EUR",
});
console.log(euro.format(9999.5));
// → "9.999,50 €"
// Preis in US-Dollar (USA)
const dollar = new Intl.NumberFormat("en-US", {
style: "currency",
currency: "USD",
});
console.log(dollar.format(9999.5));
// → "$9,999.50"Prozent, Einheiten und kompakte Notation
// Prozentwert (0.75 → 75 %)
const prozent = new Intl.NumberFormat("de-DE", {
style: "percent",
minimumFractionDigits: 1,
});
console.log(prozent.format(0.7532));
// → "75,3 %"
// Geschwindigkeit mit Einheit
const kmh = new Intl.NumberFormat("de-DE", {
style: "unit",
unit: "kilometer-per-hour",
unitDisplay: "long",
});
console.log(kmh.format(120));
// → "120 Kilometer pro Stunde"
// Kompakte Darstellung großer Zahlen
const kompakt = new Intl.NumberFormat("de-DE", {
notation: "compact",
compactDisplay: "short",
});
console.log(kompakt.format(1_500_000));
// → "1,5 Mio."
// formatToParts() für individuelles Styling
const teile = new Intl.NumberFormat("de-DE", {
style: "currency",
currency: "EUR",
}).formatToParts(1234.56);
console.log(teile.map(t => `${t.type}: "${t.value}"`).join("\n"));
/* →
integer: "1"
group: "."
integer: "234"
decimal: ","
fraction: "56"
literal: " "
currency: "€"
*/Wiederverwendung im UI (Performance-Pattern)
// Formatter einmal erstellen und cachen — effizient bei vielen Werten
const priceFormatter = new Intl.NumberFormat("de-AT", {
style: "currency",
currency: "EUR",
maximumFractionDigits: 0, // keine Cents
});
const preise = [199, 349, 999, 1249];
const formatiert = preise.map(p => priceFormatter.format(p));
console.log(formatiert);
// → ["€ 199", "€ 349", "€ 999", "€ 1.249"]// Wichtig · Fallstricke
Browser-Kompatibilität: Intl.NumberFormat ist in allen modernen Browsern und Node.js (ab v13+ mit vollständiger ICU-Daten) verfügbar. Der Umfang der unterstützten Locales hängt von der ICU-Datenbasis der Laufzeit ab — insbesondere in schlanken Node.js-Builds (small-icu) können seltene Locales fehlen.
Fallstrick style: "unit": Die Einheiten-IDs folgen dem CLDR-Standard (z. B. "kilometer-per-hour", "liter", "megabyte"). Beliebige Strings werden nicht akzeptiert — bei ungültigen Werten wirft der Konstruktor einen RangeError.
Signifikante vs. Nachkommastellen: minimumSignificantDigits/maximumSignificantDigits und minimumFractionDigits/maximumFractionDigits dürfen laut Spec nicht gleichzeitig gesetzt werden — neuere Engines unterstützen das optionale roundingPriority-Feld ("morePrecision", "lessPrecision", "auto") zur Konfliktauflösung (ES2023+).
Statische Convenience-Methode: Intl.NumberFormat.supportedLocalesOf(locales) gibt ein Array der tatsächlich unterstützten Locales zurück, ohne eine Instanz erzeugen zu müssen.