Signatur
Beschreibung
Mit format() wandelt man Datums- und Zeitwerte in Text um, der für Menschen gedacht ist. Welche Sprache, Reihenfolge, Zeitzone und Genauigkeit die Ausgabe hat, legt man vorher im Konstruktor new Intl.DateTimeFormat(locales, options) fest. Die Methode selbst bekommt nur noch das Datum.
Technisch ist format eine Getter-Eigenschaft. Sie liefert eine Funktion, die schon an ihre Instanz gebunden ist. Deshalb kann man fmt.format direkt als Rückruffunktion übergeben, z. B. an Array.prototype.map(), ohne vorher bind() aufzurufen.
Wer viele Datumswerte gleich formatiert (Tabellen, Listen, Protokolle), sollte die Instanz einmal anlegen und dann wiederverwenden. Das ist deutlich schneller als jedes Mal Date.prototype.toLocaleDateString() aufzurufen, weil dort intern bei jedem Aufruf ein neues Formatierungsobjekt entsteht.
Wenn man die einzelnen Bestandteile des Ergebnisses braucht, etwa um den Monat extra auszuzeichnen, nimmt man formatToParts(). Für Zeiträume gibt es formatRange().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $date | Date | number | undefined | Date.now() | Das Datum, das formatiert werden soll. Erlaubt sind ein Date-Objekt oder ein Zeitstempel in Millisekunden seit der Unix-Epoche. Fehlt der Wert oder ist er undefined, wird der aktuelle Zeitpunkt verwendet. In neueren Engines mit Temporal-Unterstützung sind auch passende Temporal-Objekte erlaubt. |
Rückgabewert
Beispiele
Einfache Formatierung für Deutschland
const fmt = new Intl.DateTimeFormat('de-DE');
console.log(fmt.format(new Date(2024, 2, 15)));Datum und Uhrzeit mit Stil und fester Zeitzone
const fmt = new Intl.DateTimeFormat('de-DE', {
dateStyle: 'full',
timeStyle: 'short',
timeZone: 'Europe/Berlin'
});
// 13:30 UTC entspricht 14:30 MEZ
const termin = new Date(Date.UTC(2024, 2, 15, 13, 30));
console.log(fmt.format(termin));Gebundene Funktion direkt an map() übergeben
const fmt = new Intl.DateTimeFormat('de-DE', {
day: '2-digit',
month: '2-digit',
year: 'numeric',
timeZone: 'UTC'
});
const zeitstempel = [Date.UTC(2024, 0, 1), Date.UTC(2024, 11, 24)];
// format ist schon gebunden, bind() ist nicht nötig
console.log(zeitstempel.map(fmt.format));Ungültige Datumswerte abfangen
const fmt = new Intl.DateTimeFormat('de-DE', { month: 'long', year: 'numeric' });
const sicherFormatieren = (wert) => {
const d = new Date(wert);
return Number.isNaN(d.getTime()) ? '–' : fmt.format(d);
};
console.log(sicherFormatieren('2024-03-15'));
console.log(sicherFormatieren('kaputt'));
try {
fmt.format(new Date('kaputt'));
} catch (e) {
console.log(e.name);
}// Wichtig · Fallstricke
- Ungültige Datumswerte: Ist das Datum ungültig, z. B.
new Date('abc')oderNaN, wirft die Methode einenRangeError. Sie gibt dann nicht „Invalid Date" zurück. - Ausgabe nicht fest einplanen: Der genaue Text hängt von der ICU- bzw. CLDR-Version der Engine ab. Chrome 110+ und Node.js 20+ setzen z. B. im englischen Zeitformat vor „AM/PM" ein schmales geschütztes Leerzeichen (U+202F). Wer formatierte Strings auswertet oder in Tests Zeichen für Zeichen vergleicht, bekommt dadurch Fehler. Zum Speichern und Auswerten nimmt man
toISOString()oderformatToParts(). - Zeitzone: Ohne die Option
timeZonegilt die Zeitzone des Systems. Auf Servern (Node.js, oft UTC) kann dann ein anderes Datum herauskommen als im Browser des Nutzers. Deshalb die Zeitzone ausdrücklich angeben. - Leistung: Die Instanz einmal anlegen und wiederverwenden. Die Formatierung selbst ist schnell, das Erzeugen eines neuen Formatierungsobjekts ist dagegen teuer.
dateStyle/timeStylelassen sich nicht mit einzelnen Komponenten-Optionen wiemonthoderhourkombinieren. Das führt zu einemTypeError, und zwar schon im Konstruktor.- Browser-Unterstützung: in allen modernen Browsern vorhanden.
dateStyle/timeStylegibt es erst seit 2020 (Chrome 76, Firefox 79, Safari 14.1).