Temporal.Instant.prototype.toLocaleString() — Methode · JavaScript-Referenz

Signatur

Temporal.Instant.prototype.toLocaleString(locales, options)

Beschreibung

toLocaleString() wandelt ein Temporal.Instant in einen gut lesbaren, lokalisierten Text um. Ein Instant ist ein exakter Zeitpunkt ohne Zeitzone und ohne Kalender. Deshalb muss für die Anzeige eine Zeitzone gewählt werden. Wird die Option timeZone nicht angegeben, nimmt die Methode die aktuelle Zeitzone der Laufzeitumgebung (Temporal.Now.timeZoneId()).

Die Methode verhält sich wie new Intl.DateTimeFormat(locales, options).format(instant). Ohne Optionen werden Datum und Uhrzeit numerisch ausgegeben, also Jahr, Monat, Tag, Stunde, Minute und Sekunde. Mit Optionen wie dateStyle, timeStyle, weekday, month oder timeZoneName lässt sich die Ausgabe genau steuern.

Die Methode ist nur für die Anzeige für Menschen gedacht, z. B. in Protokollansichten, Zeitstempeln in der Oberfläche oder Benachrichtigungen. Zum Speichern oder Übertragen verwendet man toString() bzw. toJSON(). Diese liefern einen eindeutigen RFC-9557-/ISO-8601-String.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| undefined	Standard-Gebietsschema der Laufzeitumgebung	BCP-47-Sprachkennung(en), z. B. `"de-DE"` oder `["de-AT", "de"]`. Genauso wie bei `Intl.DateTimeFormat`.
$options	Intl.DateTimeFormatOptions \| undefined		Formatierungsoptionen von `Intl.DateTimeFormat`, z. B. `timeZone`, `dateStyle`, `timeStyle`, `hour12`, `calendar`, `timeZoneName`. Ohne `timeZone` wird die Systemzeitzone verwendet.

Rückgabewert

Typ

string

Beschreibung

Lokalisierte Darstellung des Zeitpunkts in der gewählten bzw. der Standard-Zeitzone.

Beispiele

Einfache Ausgabe in verschiedenen Sprachen

const instant = Temporal.Instant.from("2021-08-01T12:34:56Z");

console.log(instant.toLocaleString("en-US", { timeZone: "UTC" }));
console.log(instant.toLocaleString("de-DE", { timeZone: "Europe/Berlin" }));

8/1/2021, 12:34:56 PM 1.8.2021, 14:34:56

Datums- und Zeitstil mit Zeitzonenangabe

const instant = Temporal.Instant.from("2021-08-01T12:34:56Z");

const text = instant.toLocaleString("de-DE", {
  timeZone: "Europe/Berlin",
  dateStyle: "full",
  timeStyle: "short",
});
console.log(text);

console.log(
  instant.toLocaleString("en-US", { timeZone: "UTC", timeZoneName: "short" })
);

Sonntag, 1. August 2021 um 14:34 8/1/2021, 12:34:56 PM UTC

Viele Zeitstempel effizient formatieren (Log-Ansicht)

const events = [
  { msg: "Login", at: Temporal.Instant.from("2024-03-10T08:15:00Z") },
  { msg: "Upload", at: Temporal.Instant.from("2024-03-10T08:17:42Z") },
];

// Formatter einmal anlegen statt bei jedem Aufruf neu erzeugen
const fmt = new Intl.DateTimeFormat("de-DE", {
  timeZone: "Europe/Berlin",
  dateStyle: "short",
  timeStyle: "medium",
});

for (const { msg, at } of events) {
  console.log(`${fmt.format(at)} – ${msg}`);
}

10.03.24, 09:15:00 – Login 10.03.24, 09:17:42 – Upload

// Wichtig · Fallstricke

Standard-Zeitzone: Ohne timeZone hängt die Ausgabe von der Systemzeitzone ab. Auf Server und Client kann derselbe Zeitpunkt deshalb unterschiedlich angezeigt werden. Gib timeZone ausdrücklich an, wenn die Ausgabe überall gleich sein soll.
Ausgabe nicht parsen: Das genaue Format hängt vom Browser und von der ICU-Version ab. Neuere Versionen setzen z. B. im Englischen vor „PM“ ein schmales geschütztes Leerzeichen (U+202F). Tests, die feste Strings vergleichen, können deshalb fehlschlagen. Für maschinenlesbare Werte verwendet man toString().
Leistung: Jeder Aufruf erzeugt intern möglicherweise ein neues Intl.DateTimeFormat. Wer viele Werte formatiert, legt besser einmal einen Formatter an und ruft dessen format() auf. format() nimmt Temporal-Objekte direkt entgegen.
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (Firefox 139+, Chromium 144+, Safari noch nicht). Bei Bedarf hilft ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill. Laufzeitumgebungen ohne Intl geben ggf. nur eine einfache Darstellung aus.

Siehe auch

Temporal.Instant Temporal.Instant.prototype.toString() Temporal.Instant.prototype.toJSON() Temporal.Instant.prototype.toZonedDateTimeISO() Intl.DateTimeFormat Temporal.ZonedDateTime.prototype.toLocaleString() Date.prototype.toLocaleString()