Date.prototype.toLocaleTimeString()

基线 广泛可用

此功能已得到充分确立，并且可以在许多设备和浏览器版本中使用。它已在浏览器中可用，自 2017 年 9 月.

该toLocaleTimeString()方法的Date实例返回一个字符串，其中包含此日期在本地时区的语言敏感时间部分表示形式。在具有Intl.DateTimeFormat API支持的实现中，此方法只需调用Intl.DateTimeFormat。

每次调用toLocaleTimeString时，它都必须在一个大型的本地化字符串数据库中执行搜索，这可能会导致效率低下。当使用相同的参数多次调用该方法时，最好创建一个Intl.DateTimeFormat对象并使用其format()方法，因为DateTimeFormat对象会记住传递给它的参数，并可能决定缓存数据库的一部分，以便以后的format调用可以在更受约束的上下文中搜索本地化字符串。

尝试一下

语法

js
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()返回的格式是一致的。但是，输出可能因实现而异，即使在同一语言环境中也是如此——输出差异是设计使然，并且规范允许。它也可能不是您期望的。例如，字符串可能使用不间断空格或被双向控制字符包围。您不应该将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 参数的支持

该locales和options参数可能并非在所有实现中都受支持，因为对国际化 API 的支持是可选的，并且某些系统可能没有必要的数据。对于没有国际化支持的实现，toLocaleTimeString()始终使用系统的语言环境，这可能不是您想要的。因为任何支持locales和options参数的实现都必须支持IntlAPI，所以您可以检查后者的存在以确认支持情况。

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 语言规范
# sec-date.prototype.tolocaletimestring
ECMAScript 国际化 API 规范
# sup-date.prototype.tolocaletimestring

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅