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 toLocaleString()-Methode von Temporal.PlainMonthDay-Instanzen gibt einen String mit einer sprachenspezifischen Darstellung dieses Monats-Tags zurück. 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 Lokalisierungs-Strings 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 einen Teil der Datenbank zwischenspeichert, sodass zukünftige format-Aufrufe in einem eingeschränkteren Kontext nach Lokalisierungs-Strings suchen können.

Syntax

js
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 zu 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 Unterstützung für Intl.DateTimeFormat geben denselben String wie toString() zurück und ignorieren beide Parameter.

locales Optional

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

options Optional

Ein Objekt zur Anpassung des Ausgabeformats. Entspricht dem options-Parameter des Intl.DateTimeFormat()-Konstruktors. Die calendar-Option muss mit dem gleichen Wert wie der Kalender dieses Monats-Tags angegeben werden. Bezüglich der Datum-Zeit-Komponenten-Optionen und der Stil-Abkürzungen (dateStyle und timeStyle) sollten die Optionen einer dieser Formen folgen:

  • Keine davon angeben: month und day werden standardmäßig auf "numeric" gesetzt.
  • Nur dateStyle angeben: es erweitert sich zu month und day Formaten.
  • Einige Datum-Zeit-Komponenten-Optionen angeben, wobei mindestens eine davon month oder day ist. Nur die angegebenen Datums-Komponenten werden in die Ausgabe aufgenommen.

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

Rückgabewert

Ein String, der den gegebenen 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 die von toLocaleString() zurückgegebene Formatierung konsistent. Allerdings kann die Ausgabe zwischen Implementierungen variieren, selbst innerhalb derselben Locale — Ausgabevariationen sind absichtlich und durch die Spezifikation erlaubt. Sie entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann der String nicht trennbare Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest codierten Konstanten vergleichen.

Ausnahmen

RangeError

Wirft einen Fehler, wenn eine der Optionen ungültig ist.

TypeError

Wirft einen Fehler, 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-Locale und mit den Standardoptionen 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-Tags nicht mit dem Standardkalender der Locale übereinstimmt, muss auch dann, wenn sein Kalender iso8601 ist, eine explizite calendar-Option mit dem gleichen Wert angegeben 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-Tags 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 proposal
# sec-temporal.plainmonthday.prototype.tolocalestring

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch