JavaScript/Objekte/Intl/DateTimeFormat

Die Konstruktorfunktion Intl.DateTimeFormat dient zur Erzeugung von Objekten, mit denen kulturabhängige Datums- und Zeitangaben formatiert werden können.

Syntax

   const formatter = new Intl.DateTimeFormat(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. Ein in Klammern gesetztes zweibuchstabiges Kürzel hinter dem Optionsnamen bezeichnet den Schlüssel für die Locale-Extension, über den diese Option im Locale-Tag gesetzt werden kann. Die Liste dieser Optionen ist sehr umfangreich.

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.

Locale-Optionen

localeMatcher

Siehe Übersichtsartikel

calendar (ca)

Der Kalender, der verwendet werden soll. Siehe [JavaScript/Objekte/Intl/Locale#Optionen_f.C3.BCr_die_Erzeugung_eines_Locale|Intl.Locale]].

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.

hour12

Mögliche Werte sind true und false. Diese Option aktiviert 12-Stündige (true) oder 24-Stündige (false) Zeitdarstellung und setzt die entsprechende hourCycle-Option. Welche der beiden Versionen genutzt wird (also ob die Stundenzahl bei 0 oder 1 beginnt), hängt vom jeweiligen Locale ab.

Diese Option lässt sich beim Erstellen eines Intl.Locale-Objekts nicht angeben, es gibt sie nur in Intl.DateTimeFormat.

hourCycle (hc)

Mögliche Werte sind h11 (Stunden von 0-11), h12 (Stunden von 1-12), h23 (Stunden von 0-23) und h24 (Stunden von 1-24). Du gibst mit hourCycle an, ob Du eine 12- oder 24-Stündige Zeitdarstellung möchtest und ob die Stunden bei 0 oder 1 beginnen sollen.

timeZone

Für welche Zeitzone soll eine Uhrzeit dargestellt werden. Der einzige Wert, der garantiert erkannt wird, ist UTC, und der Defaultwert ist die Zeitzone, die im Computer des Anwenders eingestellt ist. ECMA-402 Implementierungen können (aber müssen nicht) auch die Zeitzonennamen der IANA Zeitzonendatenbank erkennen, wie beispielsweise "Asia/Shanghai", "Europe/Berlin" oder "America/New_York".

Darüber hinaus gibt es etliche Optionen, die die Aufbereitung steuern und deren Anwesenheit festlegt, ob eine Zeitkomponente dargestellt werden soll oder nicht.

weekday

Wie soll der Wochentag dargestellt werden. Werte sind "long" (Langform, "Donnerstag"), "short" (Abkürzung, "Do") und "narrow" (nur Anfangsbuchstabe, d.h. mehrere Tage können den gleichen narrow-Stil haben).

era

Wie soll die Ära dargestellt werden. Werte sind "long", "short" und "narrow". Für das "de"-Locale ergibt sich immer "v. Chr." und "n. Chr.", die Option dient also nur zum Einschalten der Ära-Information. Das "en"-Locale hingegen unterscheidet "Anno Domini", "AD" und "A", bzw. "Before Christ", "BC" und "B". Die Position der Ära-Information kann von der Anwesenheit der Jahreszahl abhängen.

year

Darstellung der Jahreszahl. Mögliche Werte sind "numeric" (bis auf weiteres vierstellig) und "2-digit" (nur die beiden letzten Ziffern).

month

Darstellung des Monats. Mögliche Werte sind "numeric" ("3" oder "11"), "2-digit" ("05"), "long" ("September"), "short" ("Sep.") oder "narrow" (ein Buchstabe, ggf. nicht eindeutig).

day

Darstellung des Tages. Mögliche Werte sind numeric und 2-digit.

dayPeriod

Erweiterte Darstellung der Tagesperiode, hat nur im 12-Stündigen Modus einen Effekt. Mögliche Werte sind long, short und narrow. Etliche Locales verwenden für alle Werte den gleichen Text ("de" nicht). Wird dayPeriod angegeben, wird das bei 12-Stündiger Anzeige übliche "AM" oder "PM" durch einen längeren Text ersetzt, wie "morgens", "vormittags", "mittags" oder "nachts".

hour

Darstellung der Stunde. Mögliche Werte sind numeric und 2-digit.

minute

Darstellung der Minute. Mögliche Werte sind numeric und 2-digit.

second

Darstellung der Sekunde. Mögliche Werte sind numeric und 2-digit.

fractionalSecondDigits

Anzahl der Nachkommastellen für die Sekunde. Mögliche Werte sind von 1 bis 3. Lassen Sie die Option weg, wenn keine Nachkommastellen dargestellt werden sollen. Die Angabe von Sekundenbruchteilen aktiviert ggf. die Sekundenanzeige.

Beachte: Lasse in der Kette Stunde-Minute-Sekunde-Sekundenbruchteil keine Lücke. Die Browser müssen hierfür keine sinnvolle Ausgabe liefern. Siehe auch formatMatcher weiter unten.

timeZoneName

Die lokalisierte Darstellung der Zeitzone. Mögliche Werte sind: "long" (ausführliche lokalisierte Bezeichnung, "Mitteleuropäische Sommerzeit"), "short" (Kurzbezeichnung, "MESZ"), "longOffset" (GMT+Zeitverschiebung, "GMT+02:00"), "shortOffset" (GMT+Zeitverschiebung, "GMT+2" - Minuten werden wenn nötig hinzugefügt), shortGeneric (nicht-lokalisierte Kurzform) und longGeneric (nicht lokalisierte Langform).

Die Interpretation von kurz oder lang hängt auch davon ab, was im Locale für dieses Format gespeichert ist. Die shortGeneric-Form für Berlin ist z.B. "MEZ", für Kabul hingegen merkwürdigerweise "Afghanistan (Ortszeit)".

formatMatcher

Welcher Algorithmus verwendet werden soll, um die Optionen auf ein Darstellungsformat abzubilden. Werte sind best fit und basic. Während der basic-Algorithmus in der ECMA-402 Spezifikation festgelegt ist, ist best fit dem Browserhersteller überlassen. Für die folgenden Kombinationen aus Komponenten müssen Darstellungsformate vorhanden sein, die übrigen Kombinationen dürfen nicht funktionieren.

• weekday, year, month, day, hour, minute, second
• weekday, year, month, day
• year, month, day
• year, month
• month, day
• hour, minute, second
• hour, minute

Und schließlich gibt es noch zwei Kurzformen. Sie dürfen nicht zusammen mit den Optionen für Einzelkomponenten verwendet werden!

dateStyle

Wie soll das Datum angezeigt werden. Mögliche Werte sind full, long, medium und short. Wie diese Formatierung aussieht, hängt vom Verwendeten Locale ab.

timeStyle

Wie soll die Uhrzeit angezeigt werden. Mögliche Werte sind full, long, medium und short. Wie diese Formatierung aussieht, hängt vom Verwendeten Locale ab.