Date.prototype.toLocaleTimeString()
toLocaleTimeString()
方法是 Date
实例的一个方法,它返回一个表示此日期的时间部分的、符合语言习惯的本地化字符串(使用本地时区)。在支持 Intl.DateTimeFormat
API 的实现中,此方法会委托给 Intl.DateTimeFormat
。
每次调用 toLocaleTimeString
时,都需要在一个庞大的本地化字符串数据库中进行搜索,这可能会导致效率低下。当方法使用相同的参数被调用多次时,最好创建一个 Intl.DateTimeFormat
对象并使用其 format()
方法,因为 DateTimeFormat
对象会记住传递给它的参数,并可能决定缓存数据库的一部分,以便将来的 format
调用可以在更受限的上下文中搜索本地化字符串。
试一试
// Depending on timezone, your results will vary
const event = new Date("August 19, 1975 23:15:30 GMT+00:00");
console.log(event.toLocaleTimeString("en-US"));
// Expected output: "1:15:30 AM"
console.log(event.toLocaleTimeString("it-IT"));
// Expected output: "01:15:30"
console.log(event.toLocaleTimeString("ar-EG"));
// Expected output: "١٢:١٥:٣٠ ص"
语法
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
参数
locales
和 options
参数自定义函数行为,并允许应用程序指定应使用的语言的格式约定。
在支持 Intl.DateTimeFormat API
的实现中,这些参数与 Intl.DateTimeFormat()
构造函数的参数完全对应。不支持 Intl.DateTimeFormat
的实现则被要求忽略这两个参数,使得所使用的区域设置和返回字符串的格式完全取决于具体实现。
locales
可选-
一个带有 BCP 47 语言标签 的字符串,或此类字符串的数组。对应于
Intl.DateTimeFormat()
构造函数的locales
参数。在不支持
Intl.DateTimeFormat
的实现中,将忽略此参数,通常会使用主机的区域设置。 options
可选-
一个调整输出格式的对象。对应于
Intl.DateTimeFormat()
构造函数的options
参数。如果dayPeriod
、hour
、minute
、second
和fractionalSecondDigits
都未定义,则hour
、minute
、second
将被设置为"numeric"
。在不支持
Intl.DateTimeFormat
的实现中,将忽略此参数。
有关这些参数及其使用方法的详细信息,请参阅 Intl.DateTimeFormat()
构造函数。
返回值
一个根据语言特定约定表示给定日期时间部分的字符串。
在支持 Intl.DateTimeFormat
的实现中,这等同于 new Intl.DateTimeFormat(locales, options).format(date)
,其中 options
已按上述方式规范化。
注意: 大多数情况下,toLocaleTimeString()
返回的格式是保持一致的。然而,输出在不同实现之间可能有所不同,即使是在同一 locale 下——输出的变化是设计使然,并符合规范的允许。它也可能不是你期望的。例如,字符串可能使用不间断空格,或者被双向控制字符包围。你不应该将 toLocaleTimeString()
的结果与硬编码的常量进行比较。
示例
使用 toLocaleTimeString()
不指定 locale
的此方法的简单用法以默认区域设置和默认选项返回格式化字符串。
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
检查对 locales 和 options 参数的支持
locales
和 options
参数可能并非在所有实现中都得到支持,因为国际化 API 的支持是可选的,并且某些系统可能没有必要的数据。对于没有国际化支持的实现,toLocaleTimeString()
总是使用系统的 locale,这可能不是你想要的。由于任何支持 locales
和 options
参数的实现都必须支持 Intl
API,你可以检查后者的存在性来判断支持情况。
function toLocaleTimeStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
使用语言环境
本示例显示了一些本地化时间格式的变体。为了获得应用程序用户界面中使用的语言的格式,请确保使用 locales
参数指定该语言(以及可能的备用语言)。
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"
使用选项
可以使用 options
参数来自定义 toLocaleTimeString()
提供的结果。
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"
规范
规范 |
---|
ECMAScript® 2026 语言规范 # sec-date.prototype.tolocaletimestring |
ECMAScript® 2026 国际化 API 规范 # sup-date.prototype.tolocaletimestring |
浏览器兼容性
加载中…