Signatur
Beschreibung
Die Methode toLocaleString() wandelt ein Temporal.PlainDate in einen lesbaren Text um, der den Konventionen einer Sprache oder Region folgt, zum Beispiel 15.3.2024 für Deutsch oder 3/15/2024 für US-Englisch. In Umgebungen mit Unterstützung für die Intl-API entspricht der Aufruf new Intl.DateTimeFormat(locales, options).format(date).
Weil ein PlainDate nur ein Kalenderdatum ohne Uhrzeit und ohne Zeitzone ist, sind nur Formatoptionen für das Datum erlaubt, also year, month, day, weekday, era und dateStyle. Ohne Optionen werden Jahr, Monat und Tag numerisch ausgegeben. Eine Zeitzonen-Umrechnung findet nicht statt. Das Datum verschiebt sich also nicht um einen Tag, wie es bei Date mit UTC-Mitternacht oft passiert.
Nutze die Methode für die Anzeige in der Oberfläche, zum Beispiel für Geburtstage, Fälligkeitsdaten oder Kalenderansichten. Für das Speichern, die Übertragung oder Vergleiche nimmst du stattdessen toString() oder toJSON(), denn deren ISO-8601-Format ist eindeutig und ändert sich nicht mit der Sprache.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Intl.Locale | undefined | Standard-Sprache der Laufzeitumgebung | BCP-47-Sprachkennung wie "de-DE" oder eine Liste davon. Erweiterungen wie -u-ca-japanese (Kalender) oder -u-nu-arab (Ziffern) sind möglich. |
| $options | Intl.DateTimeFormatOptions | undefined | { year: "numeric", month: "numeric", day: "numeric" } | Formatoptionen wie bei Intl.DateTimeFormat. Erlaubt sind nur Datumsoptionen (dateStyle, year, month, day, weekday, era). Uhrzeit-Optionen wie timeStyle oder hour sowie timeZone führen zu einem TypeError. |
Rückgabewert
Beispiele
Grundlegende Formatierung in verschiedenen Sprachen
const datum = Temporal.PlainDate.from("2024-03-15");
console.log(datum.toLocaleString("de-DE"));
console.log(datum.toLocaleString("en-US"));
console.log(datum.toLocaleString("en-GB"));Ausführliche Darstellung mit dateStyle und Einzeloptionen
const faellig = Temporal.PlainDate.from({ year: 2024, month: 3, day: 15 });
console.log(faellig.toLocaleString("de-DE", { dateStyle: "full" }));
console.log(faellig.toLocaleString("de-DE", { month: "long", year: "numeric" }));
console.log(faellig.toLocaleString("de-DE", { weekday: "short", day: "numeric", month: "short" }));Formatter wiederverwenden bei vielen Datumswerten
// Bei Listen ist ein wiederverwendeter Formatter deutlich schneller
const fmt = new Intl.DateTimeFormat("de-DE", { dateStyle: "medium" });
const termine = ["2024-01-05", "2024-02-29", "2024-12-24"]
.map((s) => Temporal.PlainDate.from(s));
for (const t of termine) {
console.log(fmt.format(t));
}Uhrzeit-Optionen sind nicht erlaubt
const datum = Temporal.PlainDate.from("2024-03-15");
try {
datum.toLocaleString("de-DE", { timeStyle: "short" });
} catch (err) {
console.log(err.name);
}// Wichtig · Fallstricke
- Browser-Unterstützung: Temporal ist in Firefox ab Version 139 und in Chrome/Edge ab Version 144 verfügbar. Safari und ältere Umgebungen brauchen ein Polyfill, etwa
@js-temporal/polyfillodertemporal-polyfill. Vor der Nutzung mittypeof Temporal !== \"undefined\"prüfen. - Ausgabe nicht parsen: Das genaue Format hängt von der Laufzeitumgebung und ihren ICU/CLDR-Daten ab und kann sich zwischen Versionen ändern. Für Tests oder Speicherung
toString()verwenden. - Kalender-Konflikt: Hat das Datum einen anderen Kalender als
iso8601(z. B.hebrew) und passt dieser nicht zum Kalender des Formatters, wird einRangeErrorausgelöst. Abhilfe: den Kalender per-u-ca-…in der Sprachkennung angeben oder vorherwithCalendar()aufrufen. - Nicht erlaubte Optionen:
timeStyle,hour,minute,second,timeZoneNameundtimeZoneführen zu einemTypeError, da einPlainDatekeine Uhrzeit und keine Zeitzone hat. - Performance: Jeder Aufruf erzeugt intern einen neuen Formatter. Bei vielen Werten lieber einen
Intl.DateTimeFormateinmal anlegen undformat()wiederverwenden.