Signatur
Beschreibung
Der Konstruktor Intl.NumberFormat() liefert einen wiederverwendbaren Formatierer für Zahlen. Er berücksichtigt die Regeln der gewählten Sprache und Region: Dezimal- und Tausendertrennzeichen, die Position des Währungssymbols, Ziffernsysteme (z. B. arabisch-indische Ziffern) und Rundungsregeln. Formatiert wird über die Methode format(). Mit formatToParts() erhält man die Einzelteile als Array, formatRange() formatiert Wertebereiche.
Man nutzt den Konstruktor immer dann, wenn Zahlen für Menschen angezeigt werden: Preise im Onlineshop, Statistiken in Dashboards, Dateigrößen, Prozentwerte oder kompakte Angaben wie „1,2 Mio.“. Über options steuert man den Stil (style: "decimal", "currency", "percent", "unit"), die Schreibweise (notation: "standard", "scientific", "engineering", "compact") und die Nachkommastellen.
Der Aufruf mit oder ohne new liefert dasselbe Ergebnis. Das Erzeugen eines Formatierers kostet vergleichsweise viel Rechenzeit. Wer viele Zahlen formatiert, legt deshalb eine Instanz an und verwendet sie weiter, statt bei jedem Aufruf Number.prototype.toLocaleString() mit Optionen aufzurufen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Intl.Locale | undefined | undefined (Standard-Locale der Laufzeitumgebung) | Ein BCP-47-Sprach-Tag wie "de-DE" oder ein Array davon, sortiert nach Priorität. Unicode-Erweiterungen wie "-u-nu-arab" (Ziffernsystem) sind möglich. Wird keine passende Locale gefunden, greift eine Ausweich-Locale. |
| $options | object | {} | Konfigurationsobjekt. Wichtige Schlüssel:
|
Rückgabewert
Intl.NumberFormat-Instanz mit den Methoden format(), formatToParts(), formatRange(), formatRangeToParts() und resolvedOptions().Beispiele
Preise im Onlineshop als Euro formatieren
const euro = new Intl.NumberFormat('de-DE', {
style: 'currency',
currency: 'EUR'
});
const warenkorb = [19.9, 4.5, 1234.567];
warenkorb.forEach((preis) => console.log(euro.format(preis)));
// Gleicher Betrag, andere Region
const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
console.log(usd.format(1234.567));Kompakte Schreibweise und Prozentwerte im Dashboard
const kompakt = new Intl.NumberFormat('de-DE', {
notation: 'compact',
compactDisplay: 'short',
maximumFractionDigits: 1
});
console.log(kompakt.format(1250));
console.log(kompakt.format(3_400_000));
const prozent = new Intl.NumberFormat('de-DE', {
style: 'percent',
signDisplay: 'exceptZero',
maximumFractionDigits: 1
});
console.log(prozent.format(0.1234));
console.log(prozent.format(-0.05));Einheiten und Einzelteile mit formatToParts()
const tempo = new Intl.NumberFormat('de-DE', {
style: 'unit',
unit: 'kilometer-per-hour',
unitDisplay: 'long'
});
console.log(tempo.format(120));
const zahl = new Intl.NumberFormat('de-DE', { minimumFractionDigits: 2 });
const teile = zahl.formatToParts(9876.5);
console.log(teile.map(({ type, value }) => `${type}:${value}`).join(' | '));
console.log(zahl.resolvedOptions().locale);// Wichtig · Fallstricke
- Ausgabe nicht fest vergleichen: Die Ergebnisse hängen von der ICU-/CLDR-Version der Laufzeitumgebung ab. Oft stehen geschützte Leerzeichen darin (
U+00A0,U+202F) statt normaler Leerzeichen, z. B. vor „€“. Tests mit===gegen fest eingetragene Zeichenketten schlagen daher leicht fehl. - Kompakte Schreibweise: Im Deutschen wird „Tsd.“ standardmäßig nicht verwendet.
1250bleibt deshalb beicompactDisplay: \"short\"als „1250“ stehen. - Bei
style: \"currency\"ohnecurrencywirft der Konstruktor einenTypeError. Ungültige Sprach-Tags oder Optionswerte führen zu einemRangeError. - Standardmäßig werden bei Währungen die Nachkommastellen der jeweiligen Währung verwendet (EUR: 2, JPY: 0). Mit
minimumFractionDigitsundmaximumFractionDigitslässt sich das ändern. Der Standard fürroundingModeist\"halfExpand\"(kaufmännisches Runden). - Große Werte können als
BigIntoder als Dezimal-Zeichenkette (ES2023) übergeben werden. So bleibt die volle Genauigkeit erhalten, ohne die Ungenauigkeiten von Gleitkommazahlen. - Kompatibilität: Die Grundfunktionen laufen in allen Browsern.
notation,unitundsignDisplaygibt es seit ES2020 (Chrome 77, Firefox 78, Safari 14.1).roundingMode,formatRange()undtrailingZeroDisplaykamen mit ES2023. Node.js vor Version 13 enthält standardmäßig nur englische Sprachdaten (small-icu). - Performance: Eine Instanz sollte wiederverwendet und nicht in Schleifen oder bei jedem Rendern neu erzeugt werden.