Date.prototype.toLocaleString() — Methode · JavaScript-Referenz

Signatur

toLocaleString() / toLocaleString(locales) / toLocaleString(locales, options)

Beschreibung

Die Methode toLocaleString() von Date-Instanzen gibt einen String mit einer sprachsensitiven Repräsentation 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 Lokalisierungs-Strings 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, weil sich ein DateTimeFormat-Objekt die übergebenen Argumente merkt und möglicherweise einen Ausschnitt der Datenbank cacht, sodass zukünftige format-Aufrufe Lokalisierungs-Strings in einem eingeschränkteren Kontext suchen können.

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 exakt den Parametern des Intl.DateTimeFormat()-Konstruktors. Implementierungen ohne Intl.DateTimeFormat-Unterstützung ignorieren beide Parameter, wodurch die verwendete Locale und die Form des zurückgegebenen Strings vollständig implementierungsabhängig sind.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[]	—	Ein String mit einem BCP-47-Sprach-Tag oder ein Array solcher Strings. Entspricht dem Parameter locales des Intl.DateTimeFormat()-Konstruktors. In Implementierungen ohne Intl.DateTimeFormat-Unterstützung wird dieser Parameter ignoriert und üblicherweise die Locale des Hosts verwendet.
$options	Object	—	Ein Objekt zur Anpassung des Ausgabeformats. Entspricht dem Parameter options 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 Intl.DateTimeFormat-Unterstützung wird dieser Parameter ignoriert.

Rückgabewert

Typ

string

Beschreibung

Ein String, der das gegebene Datum gemäß sprachspezifischen Konventionen repräsentiert. In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, options).format(date).

Beispiele

toLocaleString() verwenden

const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

console.log(date.toLocaleString());
// "12/11/2012, 7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles

Unterstützung der Parameter locales und options prüfen

function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.DateTimeFormat === "function"
  );
}

locales verwenden

const date = new Date(Date.UTC(2012, 1, 2, 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"));
// "2/1/2012, 7:00:00 PM" (UTC-8 is the previous day)

// British English uses day-month-year order and 24-hour time without AM/PM
console.log(date.toLocaleString("en-GB"));
// "02/02/2012, 03:00:00" (UTC+0 or UTC+1 depending on time of the year)

// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(date.toLocaleString("ko-KR"));
// "2012. 2. 2. 오후 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"));
// "H24/2/2 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"]));
// "2/2/2012 11.00.00"

options verwenden

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));
// Example output: "Donnerstag, 20. Dezember 2012"
// The exact date may shift depending on your local time zone.

// An application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleString("en-US", options));
// Example output: "Thursday, December 20, 2012 at UTC"

// Sometimes even the US needs 24-hour time
console.log(date.toLocaleString("en-US", { hour12: false }));
// Example output: "12/19/2012, 19:00:00"
// The exact date and time may shift depending on your local time zone.

// Wichtig · Fallstricke

Meistens ist die von toLocaleString() zurückgegebene Formatierung konsistent. Die Ausgabe kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Locale – Variationen sind beabsichtigt und durch die Spezifikation erlaubt. Sie kann auch nicht dem entsprechen, was Sie erwarten. Zum Beispiel kann der String geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit hartkodierten Konstanten vergleichen.

Siehe auch

Intl.DateTimeFormat Date.prototype.toLocaleDateString() Date.prototype.toLocaleTimeString() Date.prototype.toString() Date.prototype.toDateString() Date.prototype[Symbol.toPrimitive]()