Temporal API 完全指南：JavaScript 中现代日期与时间处理方案

一. Temporal API 背景与现状

JavaScript 中的日期和时间处理一直是开发者的难题。传统的 Date 对象因设计陈旧且易出错，常让开发者头疼。因此，很多人依赖 moment.js 或 date-fns 等第三方库来弥补不足。

随着 Temporal API 的引入，JavaScript 的日期时间处理迎来了全新的解决方案。Temporal API 旨在解决传统 Date 对象的诸多问题，通过标准化的数据类型和方法，提供更易用且强大的日期时间处理能力。

1. Temporal API 主要特点

原生支持所有时区：无需第三方库即可处理复杂时区转换。
不可变性：所有操作返回新对象，不修改原对象，保证代码安全。
严格的字符串解析：遵循 ISO 8601 标准，避免解析错误。
支持非公历日历系统：适合不同文化背景的日期处理。
简化日期时间计算：提供直观 API，降低开发复杂度。

二. Temporal API 的核心数据类型

Temporal API 提供多种数据类型，涵盖与时区无关和时区相关的日期时间需求。

1. PlainDate、PlainTime 和 PlainDateTime

用于处理与时区无关的日期和时间。例如：

const date = Temporal.PlainDate.from('2024-06-21');
console.log(date.toString()); // 输出: 2024-06-21

2. ZonedDateTime

用于处理带时区的日期时间：

const zonedDateTime = Temporal.ZonedDateTime.from({
  year: 2024, month: 6, day: 21, timeZone: 'America/New_York'
});
console.log(zonedDateTime.toString()); // 输出: 2024-06-21T00:00:00-04:00[America/New_York]

3. Duration

表示时间长度，可用于日期间隔计算：

const duration = Temporal.Duration.from({ days: 5 });
console.log(duration.total('hours')); // 输出: 120

4. Instant

提供纳秒级精度，非常适合高精度场景：

const instant = Temporal.Instant.from('2024-06-21T00:00:00Z');
console.log(instant.epochNanoseconds); // 输出: 纳秒级时间戳

三. Temporal API 的优势

相比传统 Date 对象，Temporal API 在多个方面显著提升了可靠性和可用性。

1. 更可靠的日期解析

遵循 ISO 8601 标准，避免解析字符串的不确定性：

const date = Temporal.PlainDate.from('2024-06-21');
console.log(date.toString()); // 输出: 2024-06-21

2. 不可变性

所有操作返回新对象，避免修改原对象的潜在错误：

const date1 = Temporal.PlainDate.from('2024-06-21');
const date2 = date1.add({ days: 1 });
console.log(date1.toString()); // 2024-06-21
console.log(date2.toString()); // 2024-06-22

3. 强大的时区支持

内置时区功能，轻松处理全球化应用中的复杂转换：

const zonedDateTime = Temporal.ZonedDateTime.from({
  year: 2024, month: 6, day: 21, timeZone: 'Asia/Shanghai'
});
console.log(zonedDateTime.toString()); // 2024-06-21T00:00:00+08:00[Asia/Shanghai]

4. 支持非公历日历

支持多种日历系统，适合不同文化背景：

const hebrewDate = Temporal.PlainDate.from('5784-06-21[u-ca=hebrew]');
console.log(hebrewDate.toString()); // 5784-06-21[u-ca=hebrew]

四. Temporal API 使用案例

1. 获取当前日期和时间

const now = Temporal.Now.plainDateTimeISO();
console.log(now.toString()); // 输出当前日期时间

2. 日期时间计算

const date = Temporal.PlainDate.from('2024-06-21');
const newDate = date.add({ months: 1 });
console.log(newDate.toString()); // 输出: 2024-07-21

3. 比较日期

const date1 = Temporal.PlainDate.from('2024-06-21');
const date2 = Temporal.PlainDate.from('2024-07-01');
console.log(date1.until(date2).days); // 输出: 10