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 zeichenfolgenbasierte, sprachabhängige Darstellung dieses Datums-Zeitwerts zurück. In Implementierungen mit Unterstützung für die Intl.DateTimeFormat API delegiert diese Methode an Intl.DateTimeFormat und übergibt dieses Datum-Zeitwert in ein Temporal.Instant konvertiert (da Intl.DateTimeFormat ein Temporal.ZonedDateTime nicht direkt formatieren kann).

Jedes Mal, wenn toLocaleString aufgerufen wird, muss eine Suche in einer großen Datenbank von Lokalisierungszeichenfolgen durchgeführt werden, was potenziell ineffizient ist. Wenn die Methode häufig mit denselben Argumenten aufgerufen wird, ist es besser, ein Intl.DateTimeFormat Objekt zu erstellen und dessen format() Methode zu verwenden, da ein DateTimeFormat Objekt sich die übergebenen Argumente merkt und entscheiden kann, einen Teil der Datenbank zwischenzuspeichern, sodass zukünftige format-Aufrufe innerhalb eines stärker eingegrenzten Kontexts nach Lokalisierungszeichenfolgen suchen können. Allerdings unterstützt Intl.DateTimeFormat derzeit nicht das Formatieren von Temporal.ZonedDateTime Objekten, daher müssen Sie sie zuerst in Temporal.Instant Objekte umwandeln, 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 lassen Anwendungen die Sprache spezifizieren, deren Formatierungskonventionen verwendet werden sollen.

In Implementierungen, die die Intl.DateTimeFormat API unterstützen, entsprechen diese Parameter genau den Parametern des Intl.DateTimeFormat() Konstruktors. Implementierungen ohne Intl.DateTimeFormat Unterstützung geben exakt dieselbe Zeichenfolge wie toString() zurück, wobei beide Parameter ignoriert werden.

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-Zeitwerts nicht "iso8601" ist, muss die calendar Option mit demselben Wert bereitgestellt werden; andernfalls kann die calendar Option jeden Wert haben, wenn der Kalender dieses Datums-Zeitwerts "iso8601" ist. Die timeZone Option darf nicht bereitgestellt werden, da sie automatisch auf die timeZoneId des Datums-Zeitwerts gesetzt wird. In Bezug auf die Datums-Zeit-Komponentenoptionen und die Stil-Abkürzungen (dateStyle und timeStyle) sollten die Optionen eine der folgenden Formen annehmen:

  • Keine davon bereitstellen: year, month, day, hour, minute und second werden auf "numeric" voreingestellt.
  • Mindestens eine der Optionen dateStyle oder timeStyle bereitstellen: Die Datums-Zeit-Komponenten werden gemäß dem angegebenen Stil und der Sprache eingestellt.
  • Einige Datums-Zeit-Komponentenoptionen bereitstellen. Nur die angegebenen Datums-Zeit-Komponenten werden in die Ausgabe aufgenommen.

Sehen Sie den Intl.DateTimeFormat() Konstruktor für Details zu diesen Parametern und deren Verwendung.

Rückgabewert

Eine Zeichenfolge, die das gegebene Datum-Zeit nach sprachspezifischen 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 Formatierung, die von toLocaleString() zurückgegeben wird, konsistent. Allerdings kann die Ausgabe zwischen Implementierungen, sogar innerhalb derselben Sprache, variieren — Ausgabeschwankungen sind beabsichtigt und durch die Spezifikation erlaubt. Sie kann auch nicht das sein, was Sie erwarten. Beispielsweise könnte die Zeichenfolge geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest codierten Konstanten vergleichen.

Ausnahmen

RangeError

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

TypeError

Wird ausgelöst, wenn eine der Optionen nicht vom erwarteten Typ ist.

Beispiele

Verwendung von toLocaleString()

Die grundlegende Verwendung dieser Methode ohne Angabe einer locale gibt eine formatierte Zeichenfolge in der Standardsprache und mit Standardoptionen 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)

Wenn der Kalender des Datums nicht mit dem Standardkalender 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 übergeben.

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
# sec-temporal.zoneddatetime.prototype.tolocalestring

Browser-Kompatibilität

Siehe auch