JavaScript/Objekte/Intl/NumberFormat

Aus SELFHTML-Wiki
< JavaScript‎ | Objekte‎ | Intl(Weitergeleitet von Intl.NumberFormat)
Wechseln zu: Navigation, Suche

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:

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.[1]
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·107. 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)
  1. ECMA-402: Defaultwerte für Ziffernoptionen