diff --git a/files/zh-cn/web/javascript/reference/global_objects/date/tolocaletimestring/index.md b/files/zh-cn/web/javascript/reference/global_objects/date/tolocaletimestring/index.md index 244d1f3133eb4b..2c14493ecbd321 100644 --- a/files/zh-cn/web/javascript/reference/global_objects/date/tolocaletimestring/index.md +++ b/files/zh-cn/web/javascript/reference/global_objects/date/tolocaletimestring/index.md @@ -3,108 +3,118 @@ title: Date.prototype.toLocaleTimeString() slug: Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString --- -{{JSRef("Global_Objects", "Date")}} +{{JSRef}} -The **`toLocaleTimeString()`** 方法返回该日期对象时间部分的字符串，该字符串格式因不同语言而不同。新增的参数 `locales` 和 `options` 使程序能够指定使用哪种语言格式化规则，允许定制该方法的表现（behavior）。在旧版本浏览器中， `locales` 和 `options` 参数被忽略，使用的语言环境和返回的字符串格式是各自独立实现的。 +**`toLocaleTimeString()`** 方法返回该日期对象时间部分的字符串，该字符串格式因语言而异。在支持 [`Intl.DateTimeFormat` API](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 的实现中，该方法可变为简单地调用 `Intl.DateTimeFormat`。 {{EmbedInteractiveExample("pages/js/date-tolocaletimestring.html")}} ## 语法 -```plain -dateObj.toLocaleTimeString([locales [, options]]) +```js-nolint +toLocaleTimeString() +toLocaleTimeString(locales) +toLocaleTimeString(locales, options) ``` ### 参数 -查看[浏览器兼容性](#Browser_Compatibility)小节，看下哪些浏览器支持 `locales` 和 `options` 参数，还可以参看[例子：检测 `locales` 和 `options` 参数支持情况](#Example:_Checking_for_support_for_locales_and_options_arguments)。 +`locales` 和 `options` 参数使程序能够指定使用哪种语言格式化规则，允许定制该方法的行为（behavior）。 -{{page('zh-US/docs/JavaScript/Reference/Global_Objects/DateTimeFormat','Parameters')}} +在支持 [`Intl.DateTimeFormat` API](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 的实现中，这些参数与构造函数的参数完全对应。而对于不支持 `Intl.DateTimeFormat` 的实现，则要求函数忽略这两个参数，使得函数使用的区域（locale）以及返回的字符串的格式完全取决于实现。 -The default value for each date-time component property is `undefined`, but if the `hour`, `minute`, `second` properties are all `undefined`, then `hour`, `minute`, and `second` are assumed to be "numeric". +- `locales` {{optional_inline}} -## 例子 + - : 表示缩写语言代码（BCP 47 language tag）的字符串，或由此类字符串组成的数组。对应于 `Intl.DateTimeFormat()` 构造函数的 [`locales`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) 参数。 -### 例子：使用 `toLocaleTimeString` + 在不支持 `Intl.DateTimeFormat` 的实现中，该参数会被忽略，并且通常会使用主机的区域设置。 -没有指定语言环境（locale）时，返回一个使用默认语言环境和格式设置（options）的格式化字符串。 +- `options` {{optional_inline}} -```js -var 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 -alert(date.toLocaleTimeString()); -// → "7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles -``` + - : 一个调整输出格式的对象。对应于 `Intl.DateTimeFormat()` 构造函数的 [`options`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) 参数。如果其 `dayPeriod`、`hour`、`minute`、`second` 和 `fractionalSecondDigits` 属性全是 undefined，则 `hour`、`minute`、`second` 这三个属性会被设置为 `"numeric"`。 -### 例子：检测 `locales` 和 `options` 支持情况 + 在不支持 `Intl.DateTimeFormat` 的实现中，该参数会被忽略。 -`locales` 和 `options` 参数不是所有的浏览器都支持。为了检测一种实现环境（implementation）是否支持它们，可以使用不合法的语言标签，如果实现环境支持该参数，则会抛出一个 `RangeError` 异常，反之会忽略参数。 +参见 [`Intl.DateTimeFormat()` 构造函数](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat)以详细了解这些参数以及如何使用它们。 -```js -function toLocaleTimeStringSupportsLocales() { - try { - new Date().toLocaleTimeString("i"); - } catch (e) { - return e​.name === "RangeError"; - } - return false; -} -``` +### 返回值 -### 例子：使用 `locales` 参数 +一个表示给定的 {{jsxref("Global_Objects/Date", "Date")}} 实例的时间部分，且与语言相关的字符串。 -下例展示了本地化时间格式的一些变化。为了在应用的用户界面得到某种语言的时间格式，必须确保使用 `locales` 参数指定了该语言（可能还需要设置某些回退语言）。 +在支持 `Intl.DateTimeFormat` 的实现中，该方法等价于 `new Intl.DateTimeFormat(locales, options).format(date)`，其中的 `options` 已通过上述的规则进行规范化。 -```js -var 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 +当需要格式化大量的日期（date）时，最好创建一个 [`Intl.DateTimeFormat`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 对象，并使用其 [`format()`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format) 方法。 -// US English uses 12-hour time with AM/PM -alert(date.toLocaleTimeString("en-US")); -// → "7:00:00 PM" +## 示例 -// British English uses 24-hour time without AM/PM -alert(date.toLocaleTimeString("en-GB")); -// → "03:00:00" +### 使用 toLocaleTimeString() -// Korean uses 12-hour time with AM/PM -alert(date.toLocaleTimeString("ko-KR")); -// → "오후 12:00:00" +没有指定 `locale` 时，返回一个使用默认语言环境和格式设置（options）的格式化字符串。 -// Arabic in most Arabic speaking countries uses real Arabic digits -alert(date.toLocaleTimeString("ar-EG")); -// → "٧:٠٠:٠٠ م" +```js +const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0)); -// when requesting a language that may not be supported, such as -// Balinese, include a fallback language, in this case Indonesian -alert(date.toLocaleTimeString(["ban", "id"])); -// → "11.00.00" +// toLocaleTimeString() 不携带参数时，其默认区域和时区取决于实现 +console.log(date.toLocaleTimeString()); +// "11:00:00" 如果在 zh-CN 区域以及东八区（北京时间）下运行 ``` -### 例子：使用 `options` 参数 +### 使用 locales -可以使用 `options` 参数来自定义 `toLocaleTimeString` 方法返回的字符串。 +以下示例显示不同的本地化时间格式。为了获得用户界面（UI）使用的语言格式表示的字符串，请确保使用了 `locales` 参数，并将其指定为用户所使用的语言。 ```js -var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)); +const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)); -// an application may want to use UTC and make that visible -var options = {timeZone: "UTC", timeZoneName: "short"}; -alert(date.toLocaleTimeString("en-US", options)); -// → "3:00:00 AM GMT" +// 以下格式化输出均假设使用区域的本地时区； +// 对于美国，为 America/Los_Angeles -// sometimes even the US needs 24-hour time -alert(date.toLocaleTimeString("en-US", {hour12: false})); -// → "19:00:00" +// 美式英语，使用带有 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()` 所提供的结果。 -当格式化大量日期时，最好创建一个 [`Intl.DateTimeFormat`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) 对象，然后使用该对象 [`format`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/format) 属性提供的方法。 +```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" +``` ## 规范 @@ -114,9 +124,10 @@ alert(date.toLocaleTimeString("en-US", {hour12: false})); {{Compat}} -## 相关链接 +## 参见 -- {{jsxref("Global_Objects/DateTimeFormat", "DateTimeFormat")}} +- [`Intl.DateTimeFormat`](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) - {{jsxref("Date.prototype.toLocaleDateString()")}} - {{jsxref("Date.prototype.toLocaleString()")}} - {{jsxref("Date.prototype.toTimeString()")}} +- {{jsxref("Date.prototype.toString()")}}