Temporal.PlainDateTime.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 der Temporal.PlainDateTime Instanzen gibt eine zeichenkettenbasierte, sprachsensitive Darstellung dieses Datums-Zeit-Wertes 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 mit denselben Argumenten häufig 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. Somit können zukünftige format Aufrufe innerhalb eines stärker eingeschränkten Kontexts nach Lokalisierungsstrings suchen.

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 anzugeben, deren Formatierungskonventionen verwendet werden sollen.

In Implementierungen, die die Intl.DateTimeFormat API unterstützen, entsprechen diese Parameter genau denen des Intl.DateTimeFormat() Konstruktors. Implementierungen ohne Unterstützung von Intl.DateTimeFormat geben die exakt gleiche Zeichenkette wie toString() zurück, wobei beide Parameter ignoriert werden.

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. Wenn der Kalender dieses Datums-Zeit-Wertes nicht "iso8601" ist, muss die calendar Option mit demselben Wert angegeben werden; andernfalls, wenn der Kalender "iso8601" ist, kann die calendar Option beliebig sein. Bezüglich der Optionen der Datum-Zeit-Komponente und der Stilabkürzungen (dateStyle und timeStyle), sollten die Optionen eine der folgenden Formen haben:

  • Keine von ihnen angeben: year, month, day, hour, minute und second werden standardmäßig auf "numeric" gesetzt.
  • Mindestens eine von dateStyle oder timeStyle angeben: Die Datum-Zeit-Komponenten werden gemäß dem angegebenen Stil und der Lokalisierung gesetzt.
  • Einige Datum-Zeit-Komponentenoptionen angeben. Nur die angegebenen Datum-Zeit-Komponenten werden in die Ausgabe einbezogen.

Weitere Informationen zu diesen Parametern und deren Verwendung finden Sie im Intl.DateTimeFormat() Konstruktor.

Rückgabewert

Eine Zeichenkette, die das gegebene Datum-Zeit gemäß sprachspezifischer Konventionen darstellt.

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

Hinweis: Meistens ist die Formatierung, die toLocaleString() zurückgibt, konsistent. Allerdings kann die Ausgabe zwischen verschiedenen Implementierungen variieren, selbst innerhalb derselben Lokalisierung — Variationen in der Ausgabe sind entworfen und von der Spezifikation erlaubt. Sie entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann die Zeichenkette geschützte Leerzeichen verwenden oder durch bidirektionale Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest codierten 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 Standard-Lokalisierung und mit Standardoptionen zurück.

js
const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");

console.log(dt.toLocaleString()); // 8/1/2021, 12:34:56 PM (assuming en-US locale)

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

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

Verwendung von toLocaleString() mit Optionen

Sie können anpassen, welche Teile des Datums in die Ausgabe aufgenommen werden, indem Sie den options Parameter angeben.

js
const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");
dt.toLocaleString("en-US", { dateStyle: "full", timeStyle: "full" }); // Sunday, August 1, 2021 at 12:34:56 PM
dt.toLocaleString("en-US", {
  year: "numeric",
  month: "long",
  hour: "numeric",
}); // August 2021 at 12 PM
dt.toLocaleString("en-US", {
  year: "numeric",
  hour: "numeric",
  minute: "numeric",
}); // 2021, 12:34 PM

Spezifikationen

Specification
Temporal proposal
# sec-temporal.plaindatetime.prototype.tolocalestring

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch