Temporal.ZonedDateTime.prototype.toLocaleString()
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Die toLocaleString() Methode von Temporal.ZonedDateTime Instanzen gibt eine Zeichenkette mit einer sprachsensitiven Darstellung dieses Datums-Zeitpunkts zurück. In Implementierungen mit Unterstützung der Intl.DateTimeFormat API delegiert diese Methode an Intl.DateTimeFormat und übergibt diesen in eine Temporal.Instant konvertierten Datum-Zeitpunkt (da Intl.DateTimeFormat nicht direkt ein Temporal.ZonedDateTime 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 die übergebenen Argumente speichert und möglicherweise beschließt, einen Teil der Datenbank zwischenzuspeichern, sodass zukünftige format Aufrufe nach Lokalisierungszeichenfolgen in einem stärker eingeschränkten Kontext suchen können. Derzeit unterstützt Intl.DateTimeFormat jedoch nicht das Formatieren von Temporal.ZonedDateTime Objekten, daher müssen Sie diese zuerst in Temporal.Instant Objekte umwandeln, bevor Sie sie an format() übergeben.
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 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 Intl.DateTimeFormat Unterstützung geben genau dieselbe Zeichenkette wie toString() zurück und ignorieren beide Parameter.
localesOptional-
Eine Zeichenkette mit einem BCP 47 Sprach-Tag oder ein Array solcher Zeichenketten. Entspricht dem
localesParameter desIntl.DateTimeFormat()Konstruktors. optionsOptional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
optionsParameter desIntl.DateTimeFormat()Konstruktors. Wenn der Kalender dieses Datum-Zeitpunkts nicht"iso8601"ist, muss diecalendarOption mit demselben Wert angegeben werden; andernfalls, wenn der Kalender dieses Datum-Zeitpunkts"iso8601"ist, kann diecalendarOption jeden Wert haben. DietimeZoneOption darf nicht angegeben werden, da sie automatisch auf dietimeZoneIddes Datum-Zeitpunkts gesetzt wird. Bezüglich der Datums-Zeit-Komponentenoptionen und der Stil-Abkürzungen (dateStyleundtimeStyle) sollten die Optionen eine der folgenden Formen haben:- Geben Sie keine davon an:
year,month,day,hour,minuteundsecondverwenden standardmäßig"numeric". - Geben Sie mindestens eines von
dateStyleodertimeStylean: Die Datums-Zeit-Komponenten werden entsprechend dem angegebenen Stil und der Locale gesetzt. - Geben Sie einige Datums-Zeit-Komponentenoptionen an. Nur die angegebenen Datums-Zeit-Komponenten werden in die Ausgabe aufgenommen.
- Geben Sie keine davon an:
Siehe den Intl.DateTimeFormat() Konstruktor für Details zu diesen Parametern und deren Verwendung.
Rückgabewert
Eine Zeichenkette, die den gegebenen Datum-Zeitpunkt gemäß sprachspezifischen Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat ist dies gleichbedeutend mit new Intl.DateTimeFormat(locales, { ...options, timeZone: dateTime.timeZoneId }).format(dateTime.toInstant()), wobei options wie oben beschrieben normalisiert wurde.
Hinweis:
Meistens ist das von toLocaleString() zurückgegebene Format konsistent. Die Ausgabe kann jedoch zwischen verschiedenen Implementierungen variieren, sogar innerhalb derselben Locale — solche Variationen sind beabsichtigt und laut Spezifikation erlaubt. Es kann auch nicht das sein, was Sie erwarten. Zum Beispiel kann die Zeichenkette keine Trennzeichen enthalten 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 vom erwarteten Typ ist.
Beispiele
Verwendung von toLocaleString()
Die grundlegende Verwendung dieser Methode ohne Angabe einer locale gibt eine formatierte Zeichenkette in der Standardsprache mit den Standardoptionen zurück.
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 locale übereinstimmt und dieser nicht iso8601 ist, muss eine explizite calendar Option mit demselben Wert angegeben werden.
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 einbezogen werden, indem Sie den options Parameter angeben.
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 |