#Intl Enumeration API S4

中文标题：Intl 枚举 API

#Intl 枚举 API 规范

列出 ECMA 402 预置 API 中选项所支持的取值。

#第 3 阶段

• 2020 年 6 月 TC39 会议中推进到第 1 阶段。
  • 2020-06-03 会议记录
• 2020 年 9 月 TC39 会议中推进到第 2 阶段。
  • 2020-09-22 会议记录
• 2020 年 11 月 TC39 会议中的更新。
  • 2020-11-18 会议记录
• 2021 年 4 月 TC39 会议中的更新。
  • 2021-04-21 会议记录
• 2021 年 5 月 TC39 会议中的更新。
  • 2021-05-25 会议记录
• 2021 年 7 月 TC39 会议中推进到第 3 阶段
  • 2021-07-13 会议记录
• 2021 年 12 月 TC39 会议中的更新。

#TG2（ECMA402）工作会议记录：

• 2020-05-20 TG2 会议记录
• 2020-08-13 TG2 会议记录
• 2020-11-05 TG2 会议记录
• 2021-03-11 TG2 会议记录
• 2021-04-08 TG2 会议记录
• 2021-05-06 TG2 会议记录
• 2021-06-03 TG2 会议记录
• 2021-07-01 TG2 会议记录

#需要帮助！

本提案现已进入第 3 阶段，我们需要帮助向 Test262 添加测试。详见 test262 中的 Issue 3131。我们也期待看到适用于 Web 开发者的 polyfill。

#动机

ECMA402 允许支持的本地时区、排序规则、日历、编号系统和货币根据实现而定。本提案提供了一个 API 来标识这些选项在实现中支持的取值。

该 API 使调用方能够轻松地进行功能检测，以确定实现的支持情况，并可用来在加载初期轻松下载缺失功能的 polyfill。例如，网页可以检查返回值并决定是否需要导入并安装 DateTimeFormat polyfill，因为返回的时区不包含服务器存储的用户时区偏好，而 Intl.DateTimeFormat 将无法根据服务器端存储的时区偏好格式化时间。用户可能在之前使用支持该时区的其他用户代理时设置账户并将时区偏好存储在服务器端，现在需要在网吧的另一台机器上访问该 Web 应用。此 API 允许 Web 应用在首选时区不可用时进行预先检查并从服务器导入 polyfill。类似地，Web 应用可以检查支持的货币和单位集合，以实现某些 JavaScript 库动态导入 polyfill 的引导逻辑。例如，Google 的工程师目前正在更改 closure 库的实现，以在功能可用时使用 ECMA402 支持以避免不必要的下载，同时在所需支持不可用时仍下载必要数据并导入 polyfill。此 API 使库能够以最少的数据量来确定逻辑。

Web 应用还可以将本提案的 API 与 Intl.DisplayNames 和 Intl.NumberFormat 结合使用，以构建功能强大的 UI，而无需下载大量数据。例如，Web 应用可以使用此 API 获取支持的货币列表，然后使用 Intl.DisplayNames 获取货币的显示名称以构建菜单供用户选择，并使用 Intl.NumberFormat API 格式化货币金额。返回值还可支持代码决定应从服务器下载哪些货币转换信息，只下载实现能够正确格式化的货币集合，或下载所有货币表然后导入 polyfill 以支持不支持的货币。在没有此 API 的情况下，Web 应用可能为 Intl.NumberFormat 无法正确格式化的货币下载额外的货币汇率表，也无法高效确定需要与 polyfill 一起导入哪些货币格式数据。此 API 使 Web 开发者能够设计高效的系统，从服务器导入最少的信息以实现此类回退机制。

ECMA 402 也用于服务器端。基于 Node.js（基于 v8 构建并可访问 ECMA402 代码）运行的服务器端应用程序代码可以调用此 API 生成服务器已知的时区名称列表，放入 HTML 并在日历应用程序中返回给客户端。

总之，本提案的 API 是一个重要工具，使 Web 开发者能够在应用程序初始化时以最少的数据量检测缺失支持并高效导入回退 polyfill。它还允许 Web 应用结合使用其他 ECMA402 API，以从服务器端获得最少信息来编程实现强大的国际化 UI。它也是服务器端使用 ECMA402 的重要工具。

#概述

Intl 的一个方法，返回一个数组。

Intl.supportedValuesOf(key)

#支持的键

• calendar
• collation
• currency
• numberingSystem
• timeZone
• unit

#背景

https://github.com/tc39/ecma402/issues/435

#使用场景

#使用场景 1 - 检测缺失功能以触发导入 Polyfill

用户将他们的应用偏好存储在服务器端，以表示他们想要使用 ROC 日历。当用户从新手机登录应用时，应用程序代码调用此 API 并发现“roc”日历不在支持集中，便从服务器导入实现 ROC 日历的 polyfill 并使用该 polyfill。随后用户从桌面登录应用，应用程序调用此 API 发现支持“roc”日历，因此直接调用 Intl.DateTimeFormat。

#使用场景 2 - 服务器端编程

Web 程序员使用 ECMA402 代码在 Node.js 之上编写 JavaScript。应用程序（运行在 Node.js 之上的服务器端 JavaScript）调用此 API 来找出所有支持的日历、排序规则、货币、编号系统和时区以及单位，并用其生成 HTML 中的 UI 选择器发送给客户端，让用户选择他们的应用偏好。用户提交选择后，服务器端应用程序将用户的应用偏好存储到服务器端存储中。应用程序代码（运行在 Node.js 上的服务器端 JavaScript）稍后使用这些偏好值向客户端输出 HTML。

#使用场景 3 - 在 WebGL 中构建时区选择器

开发者正在使用 JavaScript 编写 WebGL 视频游戏，因此用户在屏幕上看到的所有内容都不是 HTML 渲染，而是 WebGL 中的 3D。程序员正在编写代码，让玩家控制的角色进入虚拟商店并选择他们想要用于交易虚拟商品的货币，因此程序员需要在 WebGL 中构建一个 3D GUI，列出 Intl.NumberFormat 可以支持格式化的所有货币。即使有一天所有用户代理都支持 HTML 中的此类功能，非 HTML 的解决方案也无济于事。

#现有技术

#获取时区列表

• 使用场景：
  • 如何在 JavaScript 中获取所有时区列表 - Stack Overflow
• 现有技术：
  • momentjs moment.tz.names
  • tzdb
  • countries-and-timezones
  • country-timezone

#获取货币代码列表

• 使用场景：
  • Stack Overflow 上的用户请求
• 现有技术：
  • currency-codes

#使用示例

// 找出支持的日历
Intl.supportedValuesOf("calendar").forEach(function(calendar) {
   // 'buddhist', 'chinese',  ... 'islamicc'
});

// 找出支持的货币
Intl.supportedValuesOf("currency").forEach(function(currency) {
   // 'AED', 'AFN', 'ALL', ... 'ZWL'
});

// 找出支持的编号系统
Intl.supportedValuesOf("numberingSystem").forEach(function(nu) {
  // 'adlm', 'ahom', 'arab', ...  'wara', 'wcho'
});

// 找出支持的时区
Intl.supportedValuesOf("timeZone").forEach(function(timeZone) {
  // 'Africa/Abidjan', 'Africa/Accra', ... 'Pacific/Wallis'
});

// 找出支持的单位
Intl.supportedValuesOf("unit").forEach(function(unit) {
  // 'acre', 'bit', 'byte', ... 'year'
});

#作者

• Frank Tang (@FrankYFTang)

#指定审阅者

• Shane Carr @sffc
• Jordan Harband @ljharb

#ECMAScript 编辑

• Richard Gibson @gibson042

#提案

#规范

• https://tc39.es/proposal-intl-enumeration/

#参考文献

#隐私/指纹识别风险分析

• “Intl.Enumeration Privacy Implications Mozilla’s Recommendation”., Tom Ritter, Anne van Kesteren, Steven Englehardt, Zibi Braniecki, Mozilla, Feb 4, 2021.
• 2021-03 ECMA402 会议中的讨论
• 2021-04 ECMA402 会议中的讨论（链接稍后添加）

#实现状态

• v8 跟踪 bug
• Mozilla
• JSC
• Test262

============================ 以下为忽略文本 ============================

#以下是模板内容，稍后删除

此仓库按照 TC39 template-for-proposals 的说明设置。

  你的解释器可以让读者通过 markdown 指向从 `spec.emu` 生成的 `index.html`，例如：

  ```markdown
  你可以浏览 [ecmarkup 输出](https://ACCOUNT.github.io/PROJECT/)
  或浏览 [源码](https://github.com/ACCOUNT/PROJECT/blob/master/spec.emu)。
  ```

  其中 *ACCOUNT* 和 *PROJECT* 是项目 GitHub URL 中的前两个路径元素。
  例如，对于 github.com/**tc39**/**template-for-proposals**，*ACCOUNT* 为 "tc39"，*PROJECT* 为 "template-for-proposals"。

#维护你的提案仓库

1. 修改 spec.emu（ecmarkup 使用 HTML 语法，但不是 HTML，因此我强烈建议不要将其命名为 ".html"）
2. 任何对规范有重大意义的提交都应运行 npm run build 并提交生成的输出。
3. 每当更新 ecmarkup 时，运行 npm run build 并提交该依赖产生的任何更改。