Date.prototype.toLocaleTimeString()
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 toLocaleTimeString()
Methode von Date
Instanzen gibt eine Zeichenkette mit einer sprachspezifischen Darstellung des Zeitanteils dieses Datums in der lokalen Zeitzone zurück. In Implementierungen mit Unterstützung der Intl.DateTimeFormat
API ruft diese Methode einfach Intl.DateTimeFormat
auf.
Jedes Mal, wenn toLocaleTimeString
aufgerufen wird, muss eine Suche in einer großen Datenbank mit Lokalisierungszeichenfolgen durchgeführt werden, was potenziell ineffizient ist. Wenn die Methode oft mit den gleichen Argumenten aufgerufen wird, ist es besser, ein Intl.DateTimeFormat
Objekt zu erstellen und dessen format()
Methode zu verwenden, da ein DateTimeFormat
Objekt sich die ihm übergebenen Argumente merkt und möglicherweise einen Teil der Datenbank zwischenspeichert, sodass zukünftige format
Aufrufe in einem eingeschränkteren Kontext nach Lokalisierungszeichenfolgen suchen können.
Probieren Sie es aus
Syntax
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
Parameter
Die locales
und options
Parameter 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 Unterstützung von Intl.DateTimeFormat
werden gebeten, beide Parameter zu ignorieren, wodurch die verwendete Lokalisierung und die Form der zurückgegebenen Zeichenkette vollständig von der Implementierung abhängt.
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 Unterstützung von
Intl.DateTimeFormat
wird dieser Parameter ignoriert und üblicherweise wird die Lokale des Hosts verwendet. options
Optional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
options
Parameter desIntl.DateTimeFormat()
Konstruktors. WenndayPeriod
,hour
,minute
,second
undfractionalSecondDigits
alle undefiniert sind, werdenhour
,minute
,second
auf"numeric"
gesetzt.In Implementierungen ohne Unterstützung von
Intl.DateTimeFormat
wird dieser Parameter ignoriert.
Weitere Informationen zu diesen Parametern und deren Verwendung finden Sie im Intl.DateTimeFormat()
Konstruktor.
Rückgabewert
Eine Zeichenkette, die den Zeitanteil des angegebenen Datums gemäß sprachspezifischen Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat
entspricht dies new Intl.DateTimeFormat(locales, options).format(date)
, wobei options
wie oben beschrieben normalisiert wurde.
Hinweis: Meistens ist das von toLocaleTimeString()
zurückgegebene Format konsistent. Das Ergebnis kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Lokale — Variationen der Ausgabe sind laut Spezifikation vorgesehen und erlaubt. Es kann auch nicht das sein, was Sie erwarten. Beispielsweise kann die Zeichenkette geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleTimeString()
nicht mit fest codierten Konstanten vergleichen.
Beispiele
Verwendung von toLocaleTimeString()
Die grundlegende Nutzung dieser Methode ohne Angabe einer locale
gibt eine formatierte Zeichenkette in der Standardeinstellung und mit Standardoptionen zurück.
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
// toLocaleTimeString() without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(date.toLocaleTimeString());
// "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 der Internationalisierungs-API optional ist und einige Systeme möglicherweise nicht über die erforderlichen Daten verfügen. Für Implementierungen ohne Unterstützung der Internationalisierung verwendet toLocaleTimeString()
immer die Lokale des Systems, was möglicherweise nicht das ist, was Sie möchten. Da jede Implementierung, die die Parameter locales
und options
unterstützt, auch die Intl
API unterstützen muss, können Sie die Existenz der letzteren auf Unterstützung überprüfen:
function toLocaleTimeStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
Verwendung von locales
Dieses Beispiel zeigt einige der Variationen in den lokalisierten 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 Ersatztalsprachen) mithilfe des locales
Arguments 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 12-hour time with AM/PM
console.log(date.toLocaleTimeString("en-US"));
// "7:00:00 PM"
// British English uses 24-hour time without AM/PM
console.log(date.toLocaleTimeString("en-GB"));
// "03:00:00"
// Korean uses 12-hour time with AM/PM
console.log(date.toLocaleTimeString("ko-KR"));
// "오후 12:00:00"
// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(date.toLocaleTimeString("ar-EG"));
// "٧:٠٠:٠٠ م"
// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(date.toLocaleTimeString(["ban", "id"]));
// "11.00.00"
Verwendung von options
Die von toLocaleTimeString()
bereitgestellten Ergebnisse können mit dem options
Parameter angepasst werden:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// An application may want to use UTC and make that visible
const options = { timeZone: "UTC", timeZoneName: "short" };
console.log(date.toLocaleTimeString("en-US", options));
// "3:00:00 AM GMT"
// Sometimes even the US needs 24-hour time
console.log(date.toLocaleTimeString("en-US", { hour12: false }));
// "19:00:00"
// Show only hours and minutes, use options with the default locale - use an empty array
console.log(
date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }),
);
// "20:01"
Spezifikationen
Specification |
---|
ECMAScript Language Specification # sec-date.prototype.tolocaletimestring |
ECMAScript Internationalization API Specification # sup-date.prototype.tolocaletimestring |
Browser-Kompatibilität
BCD tables only load in the browser