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 July 2015.

Die toLocaleString() Methode von Date Instanzen gibt eine sprachsensitive Darstellung dieses Datums im lokalen Zeitzonenformat 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 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 sich die übergebenen Argumente merkt und möglicherweise einen Teil der Datenbank zwischenspeichert, damit zukünftige format Aufrufe in einem eingeschränkteren Kontext nach Lokalisierungszeichenfolgen 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 ermöglichen es Anwendungen, die Sprache festzulegen, 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 sollen beide Parameter ignorieren, wodurch die verwendete Sprache und die Form der zurückgegebenen Zeichenfolge vollständig implementierungsabhängig sind.

locales Optional

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

In Implementierungen ohne Unterstützung für Intl.DateTimeFormat wird dieser Parameter ignoriert und meistens die Sprache des Hosts verwendet.

options Optional

Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem options Parameter des Intl.DateTimeFormat() Konstruktors. Wenn weekday, year, month, day, dayPeriod, hour, minute, second und fractionalSecondDigits alle undefined sind, werden year, month, day, hour, minute, second auf "numeric" gesetzt.

In Implementierungen ohne Unterstützung für Intl.DateTimeFormat wird dieser Parameter ignoriert.

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

Rückgabewert

Eine Zeichenkette, die das angegebene Datum gemäß den sprachspezifischen Konventionen darstellt.

In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, options).format(date).

Hinweis: Meistens ist das von toLocaleString() zurückgegebene Format konsistent. Das Ergebnis kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Sprache — Variationen im Ausgabeverhalten sind beabsichtigt und durch die Spezifikation erlaubt. Es kann auch nicht das sein, was Sie erwarten. Beispielsweise kann die Zeichenkette nicht trennbare Leerzeichen enthalten oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest codierten Konstanten vergleichen.

Beispiele

Verwendung von toLocaleString()

Die grundlegende Nutzung dieser Methode ohne Angabe einer locale gibt eine formatierte Zeichenkette in der Standardsprache und 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üfen der Unterstützung für die Parameter locales und options

Die locales und options Parameter werden möglicherweise nicht in allen Implementierungen unterstützt, da die Unterstützung für die Internationalisierungs-API optional ist und einige Systeme möglicherweise nicht über die erforderlichen Daten verfügen. In Implementierungen ohne Unterstützung für Internationalisierung verwendet toLocaleString() immer die Systemsprache, die möglicherweise nicht Ihren Erwartungen entspricht. Da jede Implementierung, die die Parameter locales und options unterstützt, die Intl API unterstützen muss, können Sie die Existenz dieser API auf 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 den lokalisierten Datums- und Uhrzeitformaten. Um das Format der Sprache, die in der Benutzeroberfläche Ihrer Anwendung verwendet wird, zu erhalten, geben Sie diese Sprache (und möglicherweise einige Ersatzsprachen) mit dem locales Argument an:

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 der options

Die durch 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® 2026 Language Specification # sec-date.prototype.tolocalestring
ECMAScript® 2026 Internationalization API Specification # sup-date.prototype.tolocalestring