Temporal.PlainMonthDay.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 Methode toLocaleString() von Temporal.PlainMonthDay-Instanzen gibt einen string mit einer sprachsensitiven Darstellung dieses Monats-Tages zurück. In Implementierungen mit Unterstützung der Intl.DateTimeFormat API delegiert diese Methode an Intl.DateTimeFormat.

Jedes Mal, wenn toLocaleString aufgerufen wird, muss eine Suche in einer großen Datenbank mit Lokalisierungsstrings 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 die übergebenen Argumente speichert und sich entscheiden kann, einen Teil der Datenbank im Cache zu halten, sodass zukünftige format-Aufrufe nach Lokalisierungsstrings in einem begrenzteren Kontext suchen können.

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 angeben, 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 von Intl.DateTimeFormat geben genau denselben String zurück wie toString(), ignorieren jedoch 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. Die calendar-Option muss denselben Wert wie der Kalender dieses Monats-Tages haben. Bezüglich der Datum-Uhrzeit-Komponentenoptionen und der Stilabkürzungen (dateStyle und timeStyle) sollten die Optionen eine der folgenden Formen haben:

  • Keine davon bereitstellen: month und day werden standardmäßig auf "numeric" gesetzt.
  • Nur dateStyle bereitstellen: Es wird auf month- und day-Formate erweitert.
  • Einige Datum-Uhrzeit-Komponentenoptionen angeben, wobei mindestens eine von ihnen month oder 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

Ein String, der den angegebenen Monat-Tag gemäß sprachspezifischen Konventionen darstellt.

In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, options).format(monthDay), wobei options wie oben beschrieben normalisiert wurde.

Hinweis: Meistens ist das von toLocaleString() zurückgegebene Format konsistent. Die Ausgabe kann jedoch zwischen Implementierungen variieren, selbst innerhalb desselben Gebietsschemas – Ausgabevariationen sind vom Design vorgesehen und durch die Spezifikation erlaubt. Es entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann der String durchlaufende Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest kodierten 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 einen formatierten String in der Standard-Sprache und mit Standard-Optionen zurück.

js
// Note that just specifying "08-01" defaults to the ISO 8601 calendar,
// which throws an error if the locale's default calendar is not ISO 8601.
const md = Temporal.PlainMonthDay.from("2021-08-01[u-ca=gregory]");

console.log(md.toLocaleString()); // 8/1 (assuming en-US locale and Gregorian calendar)

Wenn der Kalender des Monats-Tages nicht mit dem Standardkalender des Gebietsschemas übereinstimmt, muss selbst wenn sein Kalender iso8601 ist, eine explizite calendar-Option mit demselben Wert bereitgestellt werden.

js
const md = Temporal.PlainMonthDay.from("08-01");
md.toLocaleString("en-US", { calendar: "iso8601" }); // 08-01

Verwendung von toLocaleString() mit Optionen

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

js
const md = Temporal.PlainMonthDay.from("2021-08-01[u-ca=gregory]");
md.toLocaleString("en-US", { dateStyle: "full" }); // August 1
md.toLocaleString("en-US", { month: "long" }); // August
md.toLocaleString("en-US", { day: "numeric" }); // 1

Spezifikationen

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

Browser-Kompatibilität

Siehe auch