JavaScript Temporal API替代Date的现代日期时间处理

JavaScript原生的Date对象设计过时且存在诸多问题：可变性、月份从0开始计数、时区处理复杂且不可靠，以及API设计反直觉。为了从根本上解决这些痛点，TC39委员会提出了Temporal API提案，它提供了一套现代、不可变、时区感知的日期时间类型，旨在成为Date的长期替代品。

1. 为什么需要Temporal API？

在深入代码之前，先理解Date对象的核心缺陷：

1. 可变性：Date对象的方法（如setMonth）会修改原对象，这在复杂应用中极易引发难以追踪的bug。
2. 混乱的纪元：表示日历日期时，月份0代表一月，11代表十二月，极易出错。
3. 时区处理模糊：Date内部始终以UTC毫秒数存储，但其大多数方法（如toString）会隐式地使用本地时区，且缺乏清晰的时区标识，导致逻辑混乱。
4. 功能匮乏：缺少直接计算日期差、获取某月天数、处理不同时区等常见需求的原生方法。

Temporal API通过引入一系列全新的、职责单一的、不可变的对象来解决这些问题。

2. Temporal API核心对象一览

Temporal并非单一对象，而是一个包含多个子对象的命名空间。理解它们的职责是使用的第一步。

3. 动手实践：常用操作指南

以下步骤将引导你完成最常见的日期时间操作。

3.1 创建日期时间实例

创建 PlainDate 实例，提供年、月、日参数。注意，月份直接使用1-12的数字。

const date = new Temporal.PlainDate(2023, 10, 27);
console.log(date.toString()); // 输出: "2023-10-27"

创建 PlainTime 实例。

const time = new Temporal.PlainTime(14, 30); // 14:30
console.log(time.toString()); // 输出: "14:30:00"

创建 PlainDateTime 实例，它是日期和时间的组合。

const dateTime = new Temporal.PlainDateTime(2023, 10, 27, 14, 30);
console.log(dateTime.toString()); // 输出: "2023-10-27T14:30:00"

创建 ZonedDateTime 实例，必须提供一个IANA时区标识符。这是表示真实世界事件时间的首选方式。

const meetingTime = Temporal.ZonedDateTime.from({
  year: 2023, month: 10, day: 27,
  hour: 14, minute: 30,
  timeZone: 'Asia/Shanghai'
});
console.log(meetingTime.toString());
// 输出类似: "2023-10-27T14:30:00+08:00[Asia/Shanghai]"

3.2 从现有Date对象转换

如果需要处理遗留代码中的Date对象，可以调用 Temporal.Instant.fromEpochMilliseconds 将其转换为 Instant，然后再转换为 ZonedDateTime。

const oldDate = new Date();
const instant = Temporal.Instant.fromEpochMilliseconds(oldDate.getTime());
const zonedDateTime = instant.toZonedDateTimeISO('Europe/London'); // 指定目标时区

3.3 获取属性与不可变性

所有Temporal对象都是不可变的。要获取其属性，访问只读的属性。

const date = new Temporal.PlainDate(2023, 10, 27);
console.log(date.year);   // 2023
console.log(date.month);  // 10
console.log(date.day);    // 27
console.log(date.dayOfWeek); // 5 (星期五，1代表星期一)

尝试调用修改方法（如add、with）会返回一个全新的对象，原对象保持不变。

const original = new Temporal.PlainDate(2023, 10, 27);
const later = original.add({ days: 5 }); // 返回新对象
console.log(later.toString()); // "2023-11-01"
console.log(original.toString()); // 仍然是 "2023-10-27"

3.4 日期时间运算（加减）

使用 add 和 subtract 方法进行日期运算，参数是一个 Duration 样式的对象。

const today = new Temporal.PlainDate(2023, 10, 27);
const nextWeek = today.add({ weeks: 1 });
const lastMonth = today.subtract({ months: 1 });
const twoDaysAgo = today.subtract({ days: 2 });

计算两个日期之间的差值，使用 since 或 until 方法，返回一个 Duration 对象。

const start = new Temporal.PlainDate(2023, 10, 1);
const end = new Temporal.PlainDate(2023, 10, 27);
const duration = start.until(end);
console.log(duration.toString()); // "P26D" (表示26天)
console.log(duration.days);       // 26

如果需要更精确的（到秒）差值，应使用 ZonedDateTime 或 Instant。

const eventStart = Temporal.ZonedDateTime.from('2023-10-27T09:00:00[Asia/Shanghai]');
const eventEnd = Temporal.ZonedDateTime.from('2023-10-27T17:30:00[Asia/Shanghai]');
const duration = eventStart.until(eventEnd);
console.log(duration.toString()); // "PT8H30M" (8小时30分钟)

3.5 格式化输出（与Intl集成）

Temporal对象可以无缝地与Intl.DateTimeFormat一起使用，实现灵活、本地化的格式化。

const date = new Temporal.PlainDate(2023, 10, 27);
const formatter = new Intl.DateTimeFormat('zh-CN', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  weekday: 'long'
});
console.log(formatter.format(date)); // 输出类似: "2023年10月27日星期五"

对于 ZonedDateTime，格式化会自动包含时区信息。

const meeting = Temporal.ZonedDateTime.from('2023-10-27T14:30:00+08:00[Asia/Shanghai]');
const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full',
  timeStyle: 'long',
  timeZoneName: 'short'
});
console.log(formatter.format(meeting));
// 输出类似: "Friday, October 27, 2023 at 2:30:00 PM GMT+8"

3.6 时区转换与处理

这是 Temporal 的强项。调用 withTimeZone 方法可以在 ZonedDateTime 实例上轻松切换时区。

const tokyoTime = Temporal.ZonedDateTime.from('2023-10-27T15:00:00+09:00[Asia/Tokyo]');
const newYorkTime = tokyoTime.withTimeZone('America/New_York');
console.log(tokyoTime.toString());   // "2023-10-27T15:00:00+09:00[Asia/Tokyo]"
console.log(newYorkTime.toString()); // "2023-10-27T02:00:00-04:00[America/New_York]"
// 注意：此时东京是下午3点，纽约是当天凌晨2点（夏令时）。

获取一个时区在特定时刻的UTC偏移量。

const zone = new Temporal.TimeZone('America/Los_Angeles');
const instant = Temporal.Instant.fromEpochSeconds(1698400000); // 某个时刻
const offset = zone.getOffsetNanosecondsFor(instant);
console.log(offset / 3600000000000); // 转换为小时，例如 -7 或 -8

3.7 其他实用方法

判断一个年份是否为闰年。

const year = 2024;
console.log(Temporal.PlainDate.from(`${year}-01-01`).inLeapYear); // true
```

**获取**某个月份的天数。

```javascript
const october = new Temporal.PlainYearMonth(2023, 10);
console.log(october.daysInMonth); // 31
```

**比较**两个日期的先后。

```javascript
const dateA = new Temporal.PlainDate(2023, 10, 27);
const dateB = new Temporal.PlainDate(2023, 11, 1);
console.log(Temporal.PlainDate.compare(dateA, dateB)); // -1 (A早于B)
```

---

## 4. 实际代码示例：计算并显示会议时间

假设你需要安排一个跨越时区的会议，并**显示**各个与会者对应的本地时间。

```javascript
// 1. 定义会议时间（使用一个稳定的时区作为基准，比如UTC）
const meetingUTC = Temporal.ZonedDateTime.from('2023-11-15T14:00:00+00:00[UTC]');

// 2. 定义与会者时区
const timezones = ['America/New_York', 'Europe/London', 'Asia/Shanghai', 'Australia/Sydney'];

// 3. 创建一个格式化器
const formatter = new Intl.DateTimeFormat('zh-CN', {
  timeZoneName: 'short',
  hour: '2-digit',
  minute: '2-digit',
  hour12: false
});

// 4. 为每个时区转换并格式化输出
console.log(`全球会议时间 (基准: UTC 2023-11-15 14:00):`);
timezones.forEach(tz => {
  const localTime = meetingUTC.withTimeZone(tz);
  const formattedTime = formatter.format(localTime);
  console.log(`  ${tz}: ${formattedTime}`);
});

// 可能输出：
// 全球会议时间 (基准: UTC 2023-11-15 14:00):
//   America/New_York: 上午09:00 EST
//   Europe/London: 下午14:00 GMT
//   Asia/Shanghai: 晚上22:00 CST
//   Australia/Sydney: 次日01:00 AEDT

Temporal API目前处于Stage 3（候选提案）阶段，这意味着规范已经定稿，但尚未成为JavaScript标准的一部分。现代浏览器（如Chrome, Edge）已经开始了实验性支持（可能需要开启标志）。在生产环境中使用它，通常需要依赖社区的polyfill库，例如 @js-temporal/polyfill。

安装 polyfill库：

npm install @js-temporal/polyfill

在代码中引入：

import { Temporal } from '@js-temporal/polyfill';
// 之后即可正常使用上述所有Temporal API

通过采用Temporal API，你将获得一个更直观、更可靠、功能更强大的工具集，来彻底告别Date对象的种种不便。