Date.prototype.toLocaleTimeString()

Baseline 已广泛支持

此特性已相当成熟,可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来,各浏览器均已提供此特性。

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: "١٢:١٥:٣٠ ص"

语法

js
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)

参数

localesoptions 参数自定义函数行为,并允许应用程序指定应使用的语言的格式约定。

在支持 Intl.DateTimeFormat API 的实现中,这些参数与 Intl.DateTimeFormat() 构造函数的参数完全对应。不支持 Intl.DateTimeFormat 的实现则被要求忽略这两个参数,使得所使用的区域设置和返回字符串的格式完全取决于具体实现。

locales 可选

一个带有 BCP 47 语言标签 的字符串,或此类字符串的数组。对应于 Intl.DateTimeFormat() 构造函数的 locales 参数。

在不支持 Intl.DateTimeFormat 的实现中,将忽略此参数,通常会使用主机的区域设置。

options 可选

一个调整输出格式的对象。对应于 Intl.DateTimeFormat() 构造函数的 options 参数。如果 dayPeriodhourminutesecondfractionalSecondDigits 都未定义,则 hourminutesecond 将被设置为 "numeric"

在不支持 Intl.DateTimeFormat 的实现中,将忽略此参数。

有关这些参数及其使用方法的详细信息,请参阅 Intl.DateTimeFormat() 构造函数

返回值

一个根据语言特定约定表示给定日期时间部分的字符串。

在支持 Intl.DateTimeFormat 的实现中,这等同于 new Intl.DateTimeFormat(locales, options).format(date),其中 options 已按上述方式规范化。

注意: 大多数情况下,toLocaleTimeString() 返回的格式是保持一致的。然而,输出在不同实现之间可能有所不同,即使是在同一 locale 下——输出的变化是设计使然,并符合规范的允许。它也可能不是你期望的。例如,字符串可能使用不间断空格,或者被双向控制字符包围。你不应该将 toLocaleTimeString() 的结果与硬编码的常量进行比较。

示例

使用 toLocaleTimeString()

不指定 locale 的此方法的简单用法以默认区域设置和默认选项返回格式化字符串。

js
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 参数的支持

localesoptions 参数可能并非在所有实现中都得到支持,因为国际化 API 的支持是可选的,并且某些系统可能没有必要的数据。对于没有国际化支持的实现,toLocaleTimeString() 总是使用系统的 locale,这可能不是你想要的。由于任何支持 localesoptions 参数的实现都必须支持 Intl API,你可以检查后者的存在性来判断支持情况。

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

使用语言环境

本示例显示了一些本地化时间格式的变体。为了获得应用程序用户界面中使用的语言的格式,请确保使用 locales 参数指定该语言(以及可能的备用语言)。

js
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() 提供的结果。

js
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

浏览器兼容性

另见