Signatur
Beschreibung
Intl.DateTimeFormat ist Teil der ECMAScript-Internationalisierungs-API (Intl) und erlaubt es, Datums- und Zeitwerte (Date-Objekte oder Timestamps) gemäß den Konventionen einer bestimmten Sprache und Region zu formatieren. Dabei werden Faktoren wie Kalenderformat, Datumsreihenfolge, 12/24-Stunden-Anzeige und Monats-/Tagesnamen automatisch berücksichtigt.
Ein Intl.DateTimeFormat-Objekt wird mit einem optionalen Locale-String (z. B. 'de-DE', 'en-US') und einem optionalen Optionsobjekt instanziiert. Wichtige Optionen sind dateStyle, timeStyle sowie granulare Felder wie year, month, day, hour, minute, second und timeZone. Werden dateStyle/timeStyle zusammen mit granularen Feldern verwendet, wird ein Fehler ausgelöst.
Für wiederholte Formatierungen sollte das Intl.DateTimeFormat-Objekt einmal erstellt und mehrfach wiederverwendet werden, da die Konstruktion teurer ist als ein einzelner format()-Aufruf. Die Methode formatToParts() liefert die einzelnen Bestandteile des formatierten Datums als Array von Objekten zurück, was für individuelle Weiterverarbeitung nützlich ist. Mit formatRange() und formatRangeToParts() lassen sich Zeiträume kompakt darstellen.
- dateStyle / timeStyle:
'full','long','medium','short'– Kurzform für vordefinierte Ausgabeformate. - timeZone: IANA-Zeitzonenbezeichner, z. B.
'Europe/Berlin'. - hour12:
truefür 12-Stunden-,falsefür 24-Stunden-Format. - calendar: z. B.
'islamic','chinese','gregory'.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Systemsprache | Ein BCP-47-Sprachcode (z. B. 'de-DE', 'en-US', 'ja-JP') oder ein Array solcher Codes. Wird kein Wert angegeben, wird die Systemsprache der Laufzeitumgebung verwendet. |
| $options | object | {} | Optionsobjekt zur Steuerung der Ausgabe. Wichtige Eigenschaften: dateStyle, timeStyle, year, month, day, hour, minute, second, timeZone, hour12, weekday, era, calendar, numberingSystem, localeMatcher. |
Rückgabewert
Intl.DateTimeFormat-Instanz, die zur wiederholten Formatierung von Datumswerten verwendet werden kann.Beispiele
Einfache Datumsformatierung für verschiedene Locales
const date = new Date('2024-07-14T15:30:00Z');
// Deutsches Format
const deFormatter = new Intl.DateTimeFormat('de-DE', {
dateStyle: 'full',
timeStyle: 'short',
timeZone: 'Europe/Berlin',
});
console.log(deFormatter.format(date));
// "Sonntag, 14. Juli 2024 um 17:30"
// US-amerikanisches Format
const enFormatter = new Intl.DateTimeFormat('en-US', {
dateStyle: 'long',
timeStyle: 'short',
timeZone: 'America/New_York',
});
console.log(enFormatter.format(date));
// "July 14, 2024 at 11:30 AM"
// Japanisches Format
const jaFormatter = new Intl.DateTimeFormat('ja-JP', {
dateStyle: 'full',
timeZone: 'Asia/Tokyo',
});
console.log(jaFormatter.format(date));
// "2024年7月15日月曜日"formatToParts(), formatRange() und resolvedOptions()
const date = new Date('2024-03-15T09:05:00Z');
// formatToParts – Bestandteile einzeln auslesen
const formatter = new Intl.DateTimeFormat('de-DE', {
year: 'numeric',
month: '2-digit',
day: '2-digit',
hour: '2-digit',
minute: '2-digit',
timeZone: 'Europe/Berlin',
});
const parts = formatter.formatToParts(date);
console.log(parts);
/*
[
{ type: 'day', value: '15' },
{ type: 'literal', value: '.' },
{ type: 'month', value: '03' },
{ type: 'literal', value: '.' },
{ type: 'year', value: '2024' },
{ type: 'literal', value: ', ' },
{ type: 'hour', value: '10' },
{ type: 'literal', value: ':' },
{ type: 'minute', value: '05' },
...
]
*/
// Nur den Monatsnamen extrahieren
const monthPart = parts.find(p => p.type === 'month');
console.log('Monat:', monthPart.value); // "Monat: 03"
// formatRange – Zeitraum darstellen
const start = new Date('2024-06-01');
const end = new Date('2024-06-30');
const rangeFormatter = new Intl.DateTimeFormat('de-DE', {
year: 'numeric',
month: 'long',
day: 'numeric',
});
console.log(rangeFormatter.formatRange(start, end));
// "1.–30. Juni 2024"
// resolvedOptions – tatsächlich verwendete Einstellungen abrufen
const resolved = formatter.resolvedOptions();
console.log(resolved.locale); // "de-DE"
console.log(resolved.timeZone); // "Europe/Berlin"
console.log(resolved.calendar); // "gregory"// Wichtig · Fallstricke
Konstruktor kann ohne new aufgerufen werden: Intl.DateTimeFormat('de-DE') (ohne new) verhält sich wie new Intl.DateTimeFormat('de-DE').
Kombinations-Fehler: dateStyle/timeStyle dürfen nicht zusammen mit granularen Feldern wie year, month, day etc. verwendet werden – dies wirft einen TypeError.
Performance: Das Erstellen einer Intl.DateTimeFormat-Instanz ist relativ aufwändig. Bei der Formatierung vieler Werte sollte die Instanz einmal erstellt und wiederverwendet werden. Alternativ bietet Date.prototype.toLocaleString() eine kompaktere Schreibweise, erstellt aber intern bei jedem Aufruf ein neues Formatter-Objekt.
Zeitzonen: Als timeZone werden IANA-Zeitzonenbezeichner erwartet (z. B. 'Europe/Berlin', 'UTC'). Ungültige Werte werfen einen RangeError. In älteren Umgebungen (z. B. Node.js ohne vollständige ICU-Daten) kann die Zeitzonenunterstützung eingeschränkt sein.
Browser-Kompatibilität: Intl.DateTimeFormat ist in allen modernen Browsern verfügbar. formatRange() und formatRangeToParts() sind seit 2020/2021 weit unterstützt (Chrome 76+, Firefox 91+, Safari 14.1+).