Date.prototype.toLocaleTimeString()
toLocaleTimeString()
方法返回该日期对象时间部分的字符串,该字符串格式因语言而异。在支持 Intl.DateTimeFormat
API 的实现中,该方法仅是调用了 Intl.DateTimeFormat
方法。
尝试一下
语法
js
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
参数
locales
和 options
参数使程序能够指定使用哪种语言格式化规则,允许定制该方法的行为(behavior)。
在支持 Intl.DateTimeFormat
API 的实现中,这些参数与构造函数的参数完全对应。而对于不支持 Intl.DateTimeFormat
的实现,则要求函数忽略这两个参数,使得函数使用的区域(locale)以及返回的字符串的格式完全取决于实现。
locales
可选-
表示缩写语言代码(BCP 47 language tag)的字符串,或由此类字符串组成的数组。对应于
Intl.DateTimeFormat()
构造函数的locales
(en-US) 参数。在不支持
Intl.DateTimeFormat
的实现中,该参数会被忽略,并且通常会使用主机的区域设置。 options
可选-
一个调整输出格式的对象。对应于
Intl.DateTimeFormat()
构造函数的options
(en-US) 参数。如果其dayPeriod
、hour
、minute
、second
和fractionalSecondDigits
属性全是 undefined,则hour
、minute
、second
这三个属性会被设置为"numeric"
。在不支持
Intl.DateTimeFormat
的实现中,该参数会被忽略。
参见 Intl.DateTimeFormat()
构造函数 (en-US)以详细了解这些参数以及如何使用它们。
返回值
一个表示给定的 Date
实例的时间部分,且与语言相关的字符串。
在支持 Intl.DateTimeFormat
的实现中,该方法等价于 new Intl.DateTimeFormat(locales, options).format(date)
,其中的 options
已通过上述的规则进行规范化。
性能
当需要格式化大量的日期(date)时,最好创建一个 Intl.DateTimeFormat
对象,并使用其 format()
(en-US) 方法。
示例
使用 toLocaleTimeString()
没有指定 locale
时,返回一个使用默认语言环境和格式设置(options)的格式化字符串。
js
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
参数,并将其指定为用户所使用的语言。
js
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()
所提供的结果。
js
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