JavaScript/Objekte/Intl/NumberFormat

Die Konstruktorfunktion Intl.NumberFormat dient zur Erzeugung von Objekten, mit denen Zahlenwerte kulturabhängig formatiert werden können.

Syntax

   const formatter = new Intl.NumberFormat(locales, optionen);

locales

Die Angabe, welches Locale verwendet werden sollen. Im einfachsten Fall eine Zeichenkette mit einem BCP-47 Locale-Tag. Möglich ist auch ein Locale-Objekt oder ein Array. Mehr dazu im Übersichtsartikel.

optionen

Weitere Angaben zum gewünschten Verhalten des Formatierers. Diese Angaben werden in Form eines Objekts übergeben, dessen Eigenschaften die benötigten Verhaltensweisen festlegen. Die umfangreiche Liste dieser Optionen folgt im Anschluss.

Empfehlung: Die Konstruktorfunktion kann mit und ohne new-Operator aufgerufen werden. Der Aufruf ohne new dient der Kompatibilität mit ECMA-402 Version 1 und sollte vermieden werden.

Verwendung

Das so erzeugte formatter-Objekt kann verwendet werden, um Zahlen gemäß der bei der Erzeugung festgelegten Regeln als String zu formatieren. Dazu stellt es diese Methoden bereit:

• format()
• formatRange()
• formatToParts()
• formatRangeToParts()

Locale-Optionen

Einige dieser Optionen können als Locale-Extension dem Locale-Tag hinzugefügt werden. Das Kürzel dieser Extension ist dann in Klammern angegeben.

localeMatcher

Siehe Übersichtsartikel

numberingSystem (nu)

Das zu verwendende Zahlensystem. Das deutsche Locale gibt mit getNumberingSystems() an, dass es nur das System "Latn" unterstütze, aber es gibt mehr. Das CLDR Repository listet etliche Nummernsysteme auf, die in Form einer Ziffernliste definiert sind. All diese Nummernsysteme können Sie verwenden, beispielsweise deva (Sanskrit). Die Zahlensysteme fullwide, mathbold, mathdbl, mathmono, mathsanb und mathsans bewirken die Ausgabe mit normal erscheinenden Ziffern, aber aus den speziellen Unicode-Bereichen "Halbbreite und vollbreite Formen" bzw. "Mathematical Alphanumeric Symbols". Wer Daten aus Ihrer Webseite auslesen möchte, hat damit zunächst einmal Extraarbeit. Insbesondere ein Screenreader - also nicht zwecks Zeichenformatierung verwenden!

Siehe auch Intl.Locale.

style

Welcher Formatierungsstil verwendet werden soll. Mögliche Werte sind:

• decimal - Formatierung als einfache Zahl
• currency - Formatierung als Geldbetrag mit Währung
• percent - Formatierung als Prozentwert
• unit - Formatierung zusammen mit einer Einheit

Optionen für style: "currency"

currency

Die Währung, die verwendet wird. Hier muss ein ISO-4217 Währungscode wie USD oder EUR angegeben werden.

currencyDisplay

Wie soll die Währung angezeigt werden? Mögliche Werte sind:

• code - der ISO Währungscode (EUR)
• symbol - das Währungssymbol (€, $)
• narrowSymbol - ggf. ein verkürztes Währungssymbol. Z.B. ist die Symbol-Darstellung von australsischen Dollars A$, die narrowSymbol-Darstellung hingegen nur $
• name - der Name der Währung, in der Sprache des Locale.

currencySign

wie das Vorzeichen eines Währungsbetrags dargestellt werden soll. Mögliche Werte sind standard und accounting (Buchführung). Manche Locales stellen einen negativen Betrag im Buchführungsmodus dadurch dar, dass sie ihn einklammern, statt ein - davor zu setzen.

Optionen für style: "unit"

unit

Die zu verwendende Einheit. Die Liste möglicher Einheiten im CLDR ist sehr lang, und ECMA-402 unterstützt nur eine Teilmenge. Die ECMA-402 Spezifikation enthält dazu eine Liste der zulässigen Einheiten.

unitDisplay

Die Art der Darstellung des Einheitennamens. Möglich Werte sind long, short und narrow. Die lange Darstellung verwendet den Namen der Einheit in der Sprache des locale, die kurze und schmale Darstellung das Einheitensymbol.

Optionen für die Zahlendarstellung

minimumFractionDigits

Wieviele Nachkommastellen sollen mindestens angezeigt werden. Der Standardwert ist für den "currency"-Stil von der Währung abhängig, andernfalls ist er 0.

maximumFractionDigits

Wieviele Nachkommastellen sollen höchstens angezeigt werden. Für Währungsangaben ist der Standardwert identisch zum minimumFractionDigits-Wert, bei anderen Stilen muss diese Option angegeben werden, wenn die minimumFractionDigits größer als 0 sind.

minimumIntegerDigits

Mindestzahl der Ziffern vor dem Komma. Hat der zu formatierende Wert weniger Ziffern, wird mit Nullen aufgefüllt.

Beachten Sie: Eine Formatierung im Bank-Stil mit Sicherungssternchen oder ähnlichem ist nicht vorgesehen.

minimumSignificantDigits

maximumSignificantDigits

Minimum und Maximum der signifikanten Ziffern, die verwendet werden sollen. Ist eine Zahl größer, als signifikante Ziffern zugelassen wird, wird an der Stelle der letzten signifikanten Ziffer gerundet.

Mit signifikanten Ziffern einer Zahl sind diejenigen Ziffern einer Zahl gemeint, die ihre Genauigkeit festlegen. Beispielsweise haben die Zahlen 12345 oder 12,345 fünf signifikante Ziffern. Ob die Zahl 12300 drei, vier oder fünf signifikante Ziffern hat, ist ihr nicht anzusehen, aber wenn man 12345 mit drei signifikanten Ziffern darstellen lässt, erzeugt JavaScript "12300". Lässt man 123 mit fünf signifikanten Ziffern formatieren, entsteht "123,00"

roundingPriority

Die Angaben für signifikante Ziffern und Nachkommastellen können in Konflikt zueinander stehen. Über die roundingPriority legt man fest, wie der Konflikt aufzulösen ist.

auto

(Defaultwert) Das Ergebnis richtet sich nach den signifikanten Ziffern

morePrecision

Die Formatierungsmöglichkeit mit mehr signifikanten Ziffern wird verwendet

lessPrecision

Die Formatierungsmöglichkeit mit weniger signifikanten Ziffern wird verwendet

Die Ermittlung der Formatierungsmöglichkeit verwendet maximumFractionDigits und maximumSignificantDigits. Die Mininumgrenzen werden nicht berücksichtigt.

roundingIncrement

Ein Rundungsfaktor, Defaultwert ist 1. Seine Verwendung setzt voraus, dass roundingPriority auf "auto" gesetzt ist, keine Vorgabe für signifikante Ziffern gemacht wird und die Anzahl der minimalen und maximalen Nachkommastellen übereinstimmt. Der Rundungsfaktor legt fest, dass der Wert an der Position, die von der Nachkommastellenzahl festgelegt ist, auf ein Vielfaches des Rundungsfaktors gerundet wird. Dazu kann der Rundungsfaktor die Werte 1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, und 5000 annehmen.

Runden auf 25 Cents

const formatter = new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR", roundingIncrement: 25 });
formatter.format(123.38);
// Ergibt 123,50 €

roundingMode

Es gibt erstaunlich viele Möglichkeiten, Rundungsregeln zu formulieren.

ceil

Aufrunden (immer zum absolut größeren Wert hin)

floor

Abrunden (immer zum absolut kleineren Wert hin)

expand

Von der 0 weg runden (immer zum betragsmäßig größeren Wert hin)

trunc

Zur 0 hin runden (immer zum betragsmäßig kleineren Wert hin)

halfCeil

kaufmännisches Runden, aber immer zum absolut größeren Wert hin

halfFloor

Kaufmännisches Runden, aber immer zum absolut kleineren Wert hin

halfExpand

Standardwert. Kaufmännisches Runden gemäß DIN (immer von der 0 weg)

halfTrunc

Kaufmännisches Runden, aber immer zum betragsmäßig kleineren Wert hin

halfEven

Symmetrisches Runden gemäß IEEE 754, für Numerik, Ingenieure und Banken

trailingZeroDisplay

Steuert den Umgang mit Nullen nach dem Komma. Mögliche Werte sind auto (Defaultwert) und stripIfInteger. Im Auto-Modus werden abschließene Nullen ergänzt oder beibehalten, wenn die Angaben für Nachkommastellen oder signifikante Ziffern das so fordern. Mit stripIfInteger werden die Nachkommastellen vollständig entfernt, wenn nach dem Runden alle Nachkommastellen 0 sind

Weitere Optionen

notation

Die Formatierung, die für die Zahl verwendet werden soll. Möglich sind die Werte

standard

Normale Formatierung als Dezimalzahl

scientific

„Wissenschaftliche“ Formatierung mit Mantisse und Exponent, z.B. 1,266E7 = 1,266·10⁷. Der Betrag der Mantisse in der wissenschaftlichen Formatierung befindet sich immer im Bereich 1 ≤ m < 10.

engineering

Ingenieursversion der wissenschaftlichen Notation, die den Exponenten als Vielfaches von 3 darstellt. Der Betrag der Mantisse kann dadurch im Bereich 1 ≤ m < 1000 liegen.

compact

Eine Variante der Ingenieursversion, bei der statt einer Exponentangabe ein Zahlwort verwendet wird, z.B. 1,2 Millionen.

compactDisplay

Zusatzoption zu notation:"compact", möglich ist "short" und "long". Das de Locale verwendet in der Short-Version die Abkürzungen „Mio.“, „Mrd.“ und „Bio.“, das en Locale nur einen einzelnen Buchstaben (K, M, B und T für Kilo, Million, Billion und Trillion). In der Langversion gibt das de Locale bereits 12400 als „12 Tausend“ aus, oder „12,4 Tausend“, wenn maximumFractionDigits größer als 0 gesetzt ist.

useGrouping

Die Option steuert, ob Ziffern für die Darstellung gruppiert und ein Gruppentrennzeichen eingefügt wird, wie beispielsweise in 12.345,78. Sie kennt die Werte "always", "auto", "min2", false und true. Wie gruppiert und welches Zeichen eingesetzt wird, hängt von Locale und gegebenenfalls auch von der Währung ab.

Wichtig: false und true sind als boolesche Werte, also ohne Anführungszeichen, anzugeben!

false

Die Gruppierung wird nicht durchgeführt.

"always"

true

Die Zahl wird immer gruppiert, auch wenn diese Darstellung im Locale nicht als Default gesetzt ist.

"auto"

Ob gruppiert wird, richtet sich nach dem Locale und eventuell auch nach der Währung

"min2"

Die Zahl wird gruppiert dargestellt, wenn jede Gruppe mindestens 2 Ziffern enthält

signDisplay

Gibt an, wie das Vorzeichen dargestellt werden soll

auto

Ein Vorzeichen wird nur für negative Zahlen erzeugt und (auch für -0)

always

Ein Vorzeichen wird für positive Zahlen, für negative Zahlen und für 0 erzeugt

exceptZero

Ein Vorzeichen wird für positive und für negative Zahlen erzeugt, nicht für 0 oder -0

negative

Ein Vorzeichen wird nur negative Zahlen erzeugt, nicht für -0

never

Das Vorzeichen wird nicht dargestellt (z.B. wenn Sie eine eigene Vorzeichenaufbereitung erstellen möchten)

ECMA-402: Defaultwerte für Ziffernoptionen