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.
toLocaleTimeString()
方法返回该日期对象时间部分的字符串,该字符串格式因语言而异。在支持 Intl.DateTimeFormat
API 的实现中,该方法仅是调用了 Intl.DateTimeFormat
方法。
尝试一下
语法
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
参数
locales
和 options
参数使程序能够指定使用哪种语言格式化规则,允许定制该方法的行为(behavior)。
在支持 Intl.DateTimeFormat
API 的实现中,这些参数与构造函数的参数完全对应。而对于不支持 Intl.DateTimeFormat
的实现,则要求函数忽略这两个参数,使得函数使用的区域(locale)以及返回的字符串的格式完全取决于实现。
locales
可选-
表示缩写语言代码(BCP 47 language tag)的字符串,或由此类字符串组成的数组。对应于
Intl.DateTimeFormat()
构造函数的locales
参数。在不支持
Intl.DateTimeFormat
的实现中,该参数会被忽略,并且通常会使用主机的区域设置。 options
可选-
一个调整输出格式的对象。对应于
Intl.DateTimeFormat()
构造函数的options
参数。如果其dayPeriod
、hour
、minute
、second
和fractionalSecondDigits
属性全是 undefined,则hour
、minute
、second
这三个属性会被设置为"numeric"
。在不支持
Intl.DateTimeFormat
的实现中,该参数会被忽略。
参见 Intl.DateTimeFormat()
构造函数以详细了解这些参数以及如何使用它们。
返回值
一个表示给定的 Date
实例的时间部分,且与语言相关的字符串。
在支持 Intl.DateTimeFormat
的实现中,该方法等价于 new Intl.DateTimeFormat(locales, options).format(date)
,其中的 options
已通过上述的规则进行规范化。
性能
当需要格式化大量的日期(date)时,最好创建一个 Intl.DateTimeFormat
对象,并使用其 format()
方法。
示例
使用 toLocaleTimeString()
没有指定 locale
时,返回一个使用默认语言环境和格式设置(options)的格式化字符串。
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
// toLocaleTimeString() 不携带参数时,其默认区域和时区取决于实现
console.log(date.toLocaleTimeString());
// "11:00:00" 如果在 zh-CN 区域以及东八区(北京时间)下运行
使用 locales
以下示例显示不同的本地化时间格式。为了获得用户界面(UI)使用的语言格式表示的字符串,请确保使用了 locales
参数,并将其指定为用户所使用的语言。
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// 以下格式化输出均假设使用区域的本地时区;
// 对于美国,为 America/Los_Angeles
// 美式英语,使用带有 AM/PM 的 12 小时制
console.log(date.toLocaleTimeString("en-US"));
// "11:00:00 AM"
// 英式英语,使用不带有 AM/PM 的 24 小时制
console.log(date.toLocaleTimeString("en-GB"));
// "03:00:00"
// 韩国,使用带有 AM/PM 的 12 小时制
console.log(date.toLocaleTimeString("ko-KR"));
// "오후 12:00:00"
// 大多数阿拉伯国家使用真正的阿拉伯数字
console.log(date.toLocaleTimeString("ar-EG"));
// "٧:٠٠:٠٠ م"
// 当使用的语言不被支持,例如
// 巴厘岛语,则可以包含一种回退语言,这里以印尼语为例
console.log(date.toLocaleTimeString(["ban", "id"]));
// "11.00.00"
使用 options
可以使用 options
参数自定义 toLocaleTimeString()
所提供的结果。
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// 应用程序可能想要使用 UTC 时间,并使其可见
const options = { timeZone: "UTC", timeZoneName: "short" };
console.log(date.toLocaleTimeString("en-US", options));
// "3:00:00 AM GMT"
// 有时,区域设置为美国的情况下,需要使用 24 小时制
console.log(date.toLocaleTimeString("en-US", { hour12: false }));
// "19:00:00"
// 只显示小时和分钟,并使用默认区域——使用一个空数组
console.log(
date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }),
);
// "20:01"
规范
Specification |
---|
ECMAScript Language Specification # sec-date.prototype.tolocaletimestring |
ECMAScript Internationalization API Specification # sup-date.prototype.tolocaletimestring |
浏览器兼容性
BCD tables only load in the browser