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

五. Temporal API 高级特性

1. 自定义日历

使用 Temporal.Calendar 定义自定义日历系统，满足特定业务需求。

2. 高精度时间戳

Temporal.Instant 提供纳秒级精度，适合日志或实时数据处理。

3. 健壮的时区处理

Temporal.ZonedDateTime 可在不同时区间轻松转换，适合全球化应用。

六. 总结

Temporal API 为 JavaScript 提供现代化日期时间处理方案，解决了传统 Date 对象的诸多痛点。它具有：

功能强大
不可变性
严格解析规则
强大时区支持

未来，随着浏览器对 Temporal API 的全面支持，开发者将能更高效地处理日期时间任务，彻底告别 Date 对象的困扰。

原文链接: https://refine.dev/blog/temporal-date-api/