Temporal.PlainDate.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.PlainDate-Instanzen gibt eine zeichenfolgendarstellung dieses Datums zurück, die sprachspezifisch ist. In Implementierungen mit Unterstützung für die Intl.DateTimeFormat API delegiert diese Methode an Intl.DateTimeFormat.

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 möglicherweise entscheidet, einen Teil der Datenbank zwischenzuspeichern, sodass zukünftige format-Aufrufe innerhalb eines eingeschränkteren Kontexts nach Lokalisierungszeichenfolgen suchen können.

Syntax

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

Parameter

Die Parameter locales und options passen das Verhalten der Funktion an und ermöglichen es Anwendungen, die Sprache festzulegen, 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 Unterstützung für Intl.DateTimeFormat geben genau dieselbe Zeichenfolge zurück wie toString(), wobei beide Parameter ignoriert werden.

locales Optional

Eine Zeichenfolge mit einem BCP 47-Sprachcode oder ein Array solcher Zeichenfolgen. 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 nicht "iso8601" ist, muss die calendar-Option mit demselben Wert angegeben werden; andernfalls kann die calendar-Option bei einem "iso8601"-Kalender einen beliebigen Wert haben. In Bezug auf die Datum-/Uhrzeit-Komponentenoptionen und die Stilabkürzungen (dateStyle und timeStyle) sollten die Optionen eine der folgenden Formen haben:

Keine dieser Optionen angeben: year, month und day verwenden standardmäßig "numeric".
Nur dateStyle angeben: Dies erweitert sich zu weekday, era, year, month und day-Formaten.
Einige Datum-/Uhrzeit-Komponentenoptionen angeben, wobei mindestens eine davon eine Datumsoption (weekday, year, month, day) ist. Nur die angegebenen Datumskomponenten werden in der Ausgabe enthalten sein.

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

Rückgabewert

Eine Zeichenfolge, die das angegebene Datum gemäß den sprachspezifischen Konventionen darstellt.

In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, options).format(date), 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 Gebietsschemas — Ausgabevariationen sind von der Spezifikation vorgesehen und erlaubt. Es könnte auch nicht das sein, was Sie erwarten. Beispielsweise kann die Zeichenfolge geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit hartkodierten 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()

Einfacher Gebrauch dieser Methode ohne Angabe eines locale gibt eine formatierte Zeichenfolge in der Standardsprache und mit Standardoptionen zurück.

const date = Temporal.PlainDate.from("2021-08-01");

console.log(date.toLocaleString()); // 8/1/2021 (assuming en-US locale)

Wenn der Kalender des Datums nicht mit dem Standardkalender des Gebietsschemas übereinstimmt und der Kalender des Datums nicht iso8601 ist, muss eine explizite calendar-Option mit demselben Wert angegeben werden.

const date = Temporal.PlainDate.from("2021-08-01[u-ca=japanese]");
// The ja-JP locale uses the Gregorian calendar by default
date.toLocaleString("ja-JP", { calendar: "japanese" }); // R3/8/1

Verwendung von toLocaleString() mit Optionen

Sie können anpassen, welche Teile des Datums in der Ausgabe enthalten sind, indem Sie den options-Parameter angeben.

const date = Temporal.PlainDate.from("2021-08-01");
date.toLocaleString("en-US", { dateStyle: "full" }); // Sunday, August 1, 2021
date.toLocaleString("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric",
}); // August 1, 2021
date.toLocaleString("en-US", { year: "numeric", month: "long" }); // August 2021

Spezifikationen

Specification
Temporal # sec-temporal.plaindate.prototype.tolocalestring