sync with english version for Date.toLocaleTimeString (#10164)

* sync with english version for Date.toLocaleTimeString * Update files/zh-cn/web/javascript/reference/global_objects/date/tolocaletimestring/index.md
mdn · Nov 26, 2022 · 9271da3 · 9271da3
1 parent 1370ce1
commit 9271da3
Showing 1 changed file with 77 additions and 66 deletions.
diff --git a/.../zh-cn/web/javascript/reference/global_objects/date/tolocaletimestring/index.md b/.../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()")}}