Temporal.PlainMonthDay..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 eine sprachsensitiv formatierte Darstellung dieses Monats-Tages als Zeichenkette 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 die übergebenen Argumente speichert und möglicherweise entscheidet, einen Teil der Datenbank zwischenzuspeichern, so dass zukünftige format-Aufrufe Lokalisierungs-Strings in einem eingeschränkteren Kontext durchsuchen 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 anzugeben, 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 Intl.DateTimeFormat-Unterstützung geben genau dieselbe Zeichenkette zurück wie toString() 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 demselben Wert wie der Kalender dieses Monats-Tages angegeben werden. Bezüglich der Datum-Zeit-Komponentenoptionen und der Stil-Kurzformen (dateStyle und timeStyle) sollten die Optionen eine der folgenden Formen haben:

Keine von ihnen angeben: month und day werden als "numeric" voreingestellt.
Nur dateStyle angeben: es erweitert sich auf month- und day-Formate.
Einige Datum-Zeit-Komponentenoptionen angeben, wobei mindestens eine von ihnen month oder day ist. Nur die angegebenen Datumsbestandteile werden in die Ausgabe aufgenommen.

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

Rückgabewert

Eine Zeichenkette, die den angegebenen Monats-Tag gemäß sprachspezifischer Konventionen darstellt.

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

Hinweis: In den meisten Fällen ist die von toLocaleString() zurückgegebene Formatierung konsistent. Allerdings kann die Ausgabe zwischen verschiedenen Implementierungen, selbst innerhalb derselben Sprache, variieren — Ausgabevariationen sind absichtlich und durch die Spezifikation erlaubt. Sie ist möglicherweise auch nicht das, was Sie erwarten. Beispielsweise kann die Zeichenkette geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit festcodierten Konstanten vergleichen.

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 Standardsprache und mit Standardoptionen zurück.

// 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 der Sprache übereinstimmt, selbst wenn sein Kalender iso8601 ist, muss eine explizite calendar-Option mit demselben Wert angegeben werden.

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

Verwendung von toLocaleString() mit Optionen

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

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..tolocalestring