#Intl.ZonedDateTimeFormat ?

#Intl ZonedDateTimeFormat 提案

这是一个关于 Intl.ZonedDateTimeFormat 的提案，这是一个新的格式化器，用于支持 Temporal.ZonedDateTime 对象的格式化。

#阶段

阶段 1

• TC39 2023 年 5 月会议阶段 1 推进幻灯片
  • TG2 2023 年 5 月讨论
  • TC39 2023 年 5 月讨论

#动机

Temporal 提案 增强了现有的 Intl.DateTimeFormat 以支持一些但不是全部的 Temporal 对象：

• Temporal.PlainDateTime
• Temporal.PlainDate
• Temporal.PlainTime
• Temporal.PlainMonthDay
• Temporal.PlainYearMonth
• Temporal.Instant

其他 Temporal 对象被提议不被 Intl.DateTimeFormat 格式化：

• Temporal.Calendar
• Temporal.TimeZone
• Temporal.Duration：由 Intl.DurationFormat 格式化

在 Temporal 提案中，曾有一次早期尝试修改 Intl.DateTimeFormat 以同时格式化 Temporal.ZonedDateTime，但在关于如何从两个对象中解析 timeZone 的无休止讨论后未能达成共识（参见讨论）。

本提案提出一个新的 Intl 格式化器 Intl.ZonedDateTimeFormat，旨在格式化 Temporal.ZonedDateTime 对象，并保持 Intl.DateTimeFormat 不支持格式化 Temporal.ZonedDateTime。

#备选方案考虑

#为什么 Temporal.ZonedDateTime.prototype.toLocaleString 不能做到？

我们不能仅使用 Temporal.ZonedDateTime.prototype.toLocaleString 而需要新对象的两个原因：

• 需要格式化一个字符串来表示两个 Temporal.ZonedDateTime 之间的时间段。toLocaleString 只能为其中一个格式化字符串，而不能格式化两个 Temporal.ZonedDateTime 之间的范围。formatRange（和 formatRangeToParts）函数将能够在此对象中实现这一点。
• 某些重要信息可以被计算并缓存到对象中，以加快格式化函数期间的某些性能。

#为什么不仅仅是 Intl.DateTimeFormat？

Intl.DateTimeFormat 被设计用于格式化 Date 对象，该对象不包含 timeZone 或 Calendar。因此 Intl.DateTimeFormat 的 TimeZone 和 Calendar 在对象构造时被解析。另一方面，Temporal.ZonedDateTime 总是携带一个 TimeZone。重用 Intl.DateTimeFormat 来格式化 Temporal.ZonedDateTime 会导致 timeZone 冲突并损害 Intl.DateTimeFormat API 的纯净性。

#API 提案

#Intl.ZonedDateTimeFormat 构造函数

• 与 Intl.DateTimeFormat 相同，但如果选项包中存在 timeZone，则抛出 RangeError。

#Intl.ZonedDateTimeFormat.supportedLocales()

#Intl.ZonedDateTimeFormat.prototype.resolvedOptions()

• 不返回 timeZone

#Intl.ZonedDateTimeFormat.prototype.format(x)

• 如果 x 不是 Temporal.ZonedDateTime，则抛出 TypeError
• （稍后，我们可能决定接受一个可用于构造 Temporal.ZonedDateTime 的字符串）

#Intl.ZonedDateTimeFormat.prototype.formatToParts(x)

• 如果 x 不是 Temporal.ZonedDateTime，则抛出 TypeError
• （稍后，我们可能决定接受一个可用于构造 Temporal.ZonedDateTime 的字符串）

#Intl.ZonedDateTimeFormat.prototype.formatRange(x, y)

• 如果 x 不是 Temporal.ZonedDateTime，则抛出 TypeError
• 如果 y 不是 Temporal.ZonedDateTime，则抛出 TypeError
• 如果 x 和 y 的 timeZone 不同，则抛出 RangeError
• （稍后，我们可能决定接受可用于构造 Temporal.ZonedDateTime 的字符串作为 x 或 y）

#Intl.ZonedDateTimeFormat.prototype.formatRangeToParts(x, y)

• 如果 x 不是 Temporal.ZonedDateTime，则抛出 TypeError
• 如果 y 不是 Temporal.ZonedDateTime，则抛出 TypeError
• 如果 x 和 y 的 timeZone 不同，则抛出 RangeError
• （稍后，我们可能决定接受可用于构造 Temporal.ZonedDateTime 的字符串作为 x 或 y）

#Intl.ZonedDateTimeFormat.prototype.withTimeZone( [ timeZone ] )

• timeZone 可以是有效的 IANA 时区字符串或 undefined（表示当前用户时区）。
• 返回一个 Intl.DateTimeFormat，其 timeZone 设置为该字符串或 undefined

#Intl.DateTimeFormat.prototype.toZonedDateTimeFormat()

• 返回一个忽略内部插槽中 timeZone 的 Intl.ZonedDateTimeFormat。

---

#以下内容稍后应删除

#在创建提案之前

请确保以下事项：

1. 您已阅读流程文档
2. 您已审查现有提案
3. 您知道您的提案需要成为 TC39 的成员，或找到一位 TC39 代表来“支持”您的提案

#创建您的提案仓库

遵循以下步骤：

1. 点击仓库标题中的绿色 “使用此模板” 按钮。（注意：不要在 GitHub 网页界面中 fork 此仓库，因为那将阻止以后转移到 TC39 组织）
2. 将 biblio 更新到最新版本：npm install --save-dev --save-exact @tc39/ecma262-biblio@latest。
3. 转到您的仓库设置的“选项”页面，在“GitHub Pages”下，将源设置为根目录下的 main 分支（如果未自动保存此设置，请单击“保存”）
   1. 勾选“强制 HTTPS”
   2. 在“选项”的“功能”下，确保“Issues”已勾选，并禁用“Wiki”和“Projects”（除非您打算使用 Projects）
   3. 在“合并按钮”下，勾选“自动删除头部分支”

3. “如何编写好的解释器” 解释了如何留下良好的第一印象。

   每个 TC39 提案都应有一个 README.md 文件，该文件解释提案的目的及其高级别形态。

   ...

   本页的其余部分可用作模板 ...

   您的解释器可以通过类似 markdown 的方式将读者指向由 spec.emu 生成的 index.html：

   您可以浏览 [ecmarkup 输出](https://ACCOUNT.github.io/PROJECT/)
   或浏览 [源代码](https://github.com/ACCOUNT/PROJECT/blob/HEAD/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 并提交该依赖带来的任何更改。