Temporal.ZonedDateTime.prototype.toLocaleString()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die toLocaleString()-Methode von Temporal.ZonedDateTime-Instanzen gibt eine sprachsensitive Darstellung dieses Datums-Zeitpunkts als Zeichenkette zurück. In Implementierungen mit Unterstützung für die Intl.DateTimeFormat API wird diese Methode an Intl.DateTimeFormat delegiert und übergibt diesen Datums-Zeitpunkt als in eine Temporal.Instant konvertierte Instanz (da Intl.DateTimeFormat ein Temporal.ZonedDateTime nicht direkt formatieren kann).

Jedes Mal, wenn toLocaleString aufgerufen wird, muss in einer großen Datenbank nach Lokalisierungszeichenketten gesucht werden, was potenziell ineffizient ist. Wenn die Methode häufig mit denselben Argumenten aufgerufen wird, ist es effizienter, ein Intl.DateTimeFormat-Objekt zu erstellen und dessen format()-Methode zu verwenden, da ein DateTimeFormat-Objekt sich die übergebenen Argumente merkt und möglicherweise einen Teil der Datenbank zwischenspeichert, damit zukünftige format-Aufrufe Lokalisierungszeichenketten in einem eingeschränkteren Kontext suchen können. Aktuell unterstützt Intl.DateTimeFormat jedoch das Formatieren von Temporal.ZonedDateTime-Objekten nicht, sodass Sie diese zunächst in Temporal.Instant-Objekte umwandeln müssen, bevor Sie sie an format() übergeben.

Syntax

js
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Parameter

Die Parameter locales und options passen das Verhalten der Funktion an und ermöglichen Anwendungen, die Sprache zu spezifizieren, deren Formatierungskonventionen verwendet werden sollen.

In Implementierungen, die die Intl.DateTimeFormat API unterstützen, entsprechen diese Parameter genau den Parametern des Konstruktors Intl.DateTimeFormat(). Implementierungen ohne Unterstützung für Intl.DateTimeFormat geben dieselbe Zeichenkette zurück wie toString() und ignorieren beide Parameter.

locales Optional

Ein String mit einem BCP 47-Sprach-Tag oder ein Array solcher Strings. Entspricht dem locales-Parameter des Intl.DateTimeFormat()-Konstruktors.

options Optional

Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem options-Parameter des Intl.DateTimeFormat()-Konstruktors. Wenn der Kalender dieses Datums-Zeitpunkts nicht "iso8601" ist, muss die calendar-Option mit demselben Wert angegeben werden; andernfalls kann die calendar-Option bei einem "iso8601"-Kalender jeden beliebigen Wert haben. Die timeZone-Option darf nicht angegeben werden, da sie automatisch auf die timeZoneId dieses Datums-Zeitpunkts gesetzt wird. Hinsichtlich der Date-Time-Komponentenoptionen und der Stil-Abkürzungen (dateStyle und timeStyle) sollten die Optionen eine der folgenden Formen erfüllen:

  • Keine davon angeben: year, month, day, hour, minute und second werden standardmäßig auf "numeric" gesetzt.
  • Mindestens eine der Optionen dateStyle oder timeStyle angeben: Die Datums-Zeit-Komponenten werden gemäß dem angegebenen Stil und der angegebenen Sprache gesetzt.
  • Einige Date-Time-Komponentenoptionen angeben: Nur die angegebenen Datums-Zeit-Komponenten werden in die Ausgabe einbezogen.

Weitere Details zu diesen Parametern und ihrer Verwendung finden Sie im Intl.DateTimeFormat()-Konstruktor.

Rückgabewert

Eine Zeichenkette, die den angegebenen Datums-Zeitpunkt entsprechend sprachspezifischer Konventionen darstellt.

In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, { ...options, timeZone: dateTime.timeZoneId }).format(dateTime.toInstant()), wobei options wie oben beschrieben normalisiert wurde.

Hinweis: Meistens ist die von toLocaleString() zurückgegebene Formatierung konsistent. Allerdings kann die Ausgabe je nach Implementierung variieren, selbst innerhalb desselben Sprachraums – Variationen in der Ausgabe sind spezifikationskonform und gewollt. Sie entspricht möglicherweise auch nicht Ihren Erwartungen. Die Zeichenkette kann z. B. geschützte Leerzeichen enthalten oder von bidirektionalen Steuerzeichen umgeben sein. Vergleichen Sie die Ergebnisse von toLocaleString() nicht mit fest codierten Konstanten.

Ausnahmen

RangeError

Wird ausgelöst, wenn eine der Optionen ungültig ist.

TypeError

Wird ausgelöst, wenn eine der Optionen nicht den erwarteten Typ hat.

Beispiele

Verwendung von toLocaleString()

Die grundlegende Verwendung dieser Methode ohne Angabe einer locale gibt eine formatierte Zeichenkette in der standardmäßigen Sprache und mit standardmäßigen Optionen zurück.

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56-04:00[America/New_York]",
);

console.log(zdt.toLocaleString()); // 8/1/2021, 12:34:56 PM EDT (assuming en-US locale)

Falls der Kalender des Datums nicht mit dem standardmäßigen Kalender der Sprache übereinstimmt und der Kalender des Datums nicht iso8601 ist, muss explizit eine calendar-Option mit demselben Wert angegeben werden.

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56+09:00[Asia/Tokyo][u-ca=japanese]",
);
// The ja-JP locale uses the Gregorian calendar by default
zdt.toLocaleString("ja-JP", { calendar: "japanese" }); // R3/8/1 12:34:56 JST

Verwendung von toLocaleString() mit Optionen

Sie können anpassen, welche Teile des Datums in die Ausgabe aufgenommen werden, indem Sie den options-Parameter angeben.

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56+09:00[Asia/Tokyo][u-ca=japanese]",
);
zdt.toLocaleString("ja-JP", {
  calendar: "japanese",
  dateStyle: "full",
  timeStyle: "full",
}); // 令和3年8月1日日曜日 12時34分56秒 日本標準時
zdt.toLocaleString("ja-JP", {
  calendar: "japanese",
  year: "numeric",
  month: "long",
  hour: "numeric",
  timeZoneName: "shortGeneric",
}); // 令和3年8月 12時 JST
zdt.toLocaleString("ja-JP", {
  calendar: "japanese",
  year: "numeric",
  hour: "numeric",
  minute: "numeric",
}); // 令和3年 12:34

Spezifikationen

Specification
Temporal proposal
# sec-temporal.zoneddatetime.prototype.tolocalestring

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch