Date.prototype.toLocaleString()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.
Die toLocaleString()
Methode von Date
Instanzen gibt einen sprachsensitiven String mit der Darstellung dieses Datums in der lokalen Zeitzone 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 von Lokalisierungsstrings durchgeführt werden, was potenziell ineffizient ist. Wenn die Methode viele Male 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 nach Lokalisierungsstrings in einem stärker eingeschränkten Kontext suchen können.
Probieren Sie es aus
const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(event.toLocaleString("en-GB", { timeZone: "UTC" }));
// Expected output: "20/12/2012, 03:00:00"
// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(event.toLocaleString("ko-KR", { timeZone: "UTC" }));
// Expected output: "2012. 12. 20. 오전 3:00:00"
Syntax
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
Parameter
Die locales
und options
Parameter 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 Intl.DateTimeFormat
Unterstützung werden angewiesen, beide Parameter zu ignorieren, wodurch die verwendete Locale und die Form des zurückgegebenen Strings vollständig implementierungsabhängig sind.
locales
Optional-
Ein String mit einem BCP 47 Sprach-Tag oder ein Array solcher Strings. Entspricht dem
locales
Parameter desIntl.DateTimeFormat()
Konstruktors.In Implementierungen ohne
Intl.DateTimeFormat
Unterstützung wird dieser Parameter ignoriert und normalerweise die Locale des Hosts verwendet. options
Optional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
options
Parameter desIntl.DateTimeFormat()
Konstruktors. Wennweekday
,year
,month
,day
,dayPeriod
,hour
,minute
,second
undfractionalSecondDigits
alle undefiniert sind, werdenyear
,month
,day
,hour
,minute
,second
auf"numeric"
gesetzt.In Implementierungen ohne
Intl.DateTimeFormat
Unterstützung wird dieser Parameter ignoriert.
Siehe den Intl.DateTimeFormat()
Konstruktor für Details zu diesen Parametern und deren Verwendung.
Rückgabewert
Ein String, der das gegebene Datum entsprechend sprachspezifischer Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat
ist dies äquivalent zu new Intl.DateTimeFormat(locales, options).format(date)
.
Hinweis:
Meistens ist das von toLocaleString()
zurückgegebene Format konsistent. Die Ausgabe kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Locale — Variationen sind absichtlich und durch die Spezifikation erlaubt. Es ist möglicherweise auch nicht das, was Sie erwarten. Zum Beispiel könnte der String nicht-trennende Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString()
nicht mit festcodierten Konstanten vergleichen.
Beispiele
Verwendung von toLocaleString()
Die grundlegende Verwendung dieser Methode ohne Angabe einer locale
gibt einen formatierten String in der Standard-Locale mit Standardoptionen zurück.
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
// toLocaleString() without arguments depends on the
// implementation, the default locale, and the default time zone
console.log(date.toLocaleString());
// "12/11/2012, 7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles
Überprüfung der Unterstützung für locales
und options
Parameter
Die locales
und options
Parameter werden möglicherweise nicht in allen Implementierungen unterstützt, da die Unterstützung der Internationalisierungs-API optional ist und einige Systeme nicht die erforderlichen Daten haben. Für Implementierungen ohne Internationalisierungsunterstützung verwendet toLocaleString()
immer die Locale des Systems, was möglicherweise nicht das Gewünschte ist. Weil jede Implementierung, die die locales
und options
Parameter unterstützt, auch die Intl
API unterstützen muss, können Sie die Existenz der letzteren zur Unterstützung überprüfen:
function toLocaleStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
Verwendung von locales
Dieses Beispiel zeigt einige der Variationen in lokalisierten Datums- und Zeitformaten. Um das Format der Sprache zu erhalten, die in der Benutzeroberfläche Ihrer Anwendung verwendet wird, stellen Sie sicher, dass Sie diese Sprache (und möglicherweise einige Ausweichsprachen) mit dem locales
Argument angeben:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// Formats below assume the local time zone of the locale;
// America/Los_Angeles for the US
// US English uses month-day-year order and 12-hour time with AM/PM
console.log(date.toLocaleString("en-US"));
// "12/19/2012, 7:00:00 PM"
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(date.toLocaleString("en-GB"));
// "20/12/2012 03:00:00"
// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(date.toLocaleString("ko-KR"));
// "2012. 12. 20. 오후 12:00:00"
// Arabic in most Arabic-speaking countries uses Eastern Arabic numerals
console.log(date.toLocaleString("ar-EG"));
// "٢٠/١٢/٢٠١٢ ٥:٠٠:٠٠ ص"
// For Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(date.toLocaleString("ja-JP-u-ca-japanese"));
// "24/12/20 12:00:00"
// When requesting a language that may not be supported, such as
// Balinese, include a fallback language (in this case, Indonesian)
console.log(date.toLocaleString(["ban", "id"]));
// "20/12/2012 11.00.00"
Verwendung von options
Die von toLocaleString()
bereitgestellten Ergebnisse können mit dem options
Parameter angepasst werden:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// Request a weekday along with a long date
const options = {
weekday: "long",
year: "numeric",
month: "long",
day: "numeric",
};
console.log(date.toLocaleString("de-DE", options));
// "Donnerstag, 20. Dezember 2012"
// An application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleString("en-US", options));
// "Thursday, December 20, 2012, GMT"
// Sometimes even the US needs 24-hour time
console.log(date.toLocaleString("en-US", { hour12: false }));
// "12/19/2012, 19:00:00"
Spezifikationen
Specification |
---|
ECMAScript® 2025 Language Specification # sec-date.prototype.tolocalestring |
ECMAScript® 2025 Internationalization API Specification # sup-date.prototype.tolocalestring |