JavaScript Temporal API 完整指南：现代化日期时间处理与实战

一. 为什么要关注 Temporal API

在 JavaScript 中处理日期和时间一直是开发者的挑战。传统的 Date API 不够灵活，易出错，因此许多开发者依赖第三方库。
Temporal API 的出现，为日期时间处理带来了革命性的改变。

1. Date API 的局限性

• 时区支持不足：Date 对象无法自动理解上下文时区。
• 解析规则不一致：不同浏览器和环境可能导致结果不确定。
• 操作复杂：日期加减等操作需要大量样板代码，易出错。

2. Temporal API 的优势

• 不可变性：每次操作返回新实例，避免意外修改。
• 明确时区支持：只需指定一次时区，API 自动处理转换。
• 现代化设计：强制 ISO 日期格式，解析一致。
• 性能优化：减少不必要的时区计算和格式转换。

二. 在项目中启用 Temporal API

1. 安装 polyfill

由于 Temporal API 仍在提案阶段，主流浏览器尚未完全支持，可通过 @js-temporal/polyfill 使用：

npm install @js-temporal/polyfill

2. 导入 polyfill

import '@js-temporal/polyfill';

完成后即可在项目中使用 Temporal API 功能。

三. Temporal API 核心数据类型

Temporal 提供两类主要数据类型：Plain 类型和 Zoned 类型。

1. Plain 类型

表示不含时区的日期或时间，适合不需特定时区的场景，例如 PlainDateTime：

const plainDateTime = Temporal.PlainDateTime.from('2023-10-15T10:00');
console.log(plainDateTime.toString()); // 2023-10-15T10:00:00

2. Zoned 类型

表示带时区的日期和时间，例如 ZonedDateTime：

const zonedDateTime = Temporal.ZonedDateTime.from({
  year: 2023,
  month: 10,
  day: 15,
  hour: 10,
  timeZone: 'America/New_York'
});
console.log(zonedDateTime.toString()); // 2023-10-15T10:00:00-04:00[America/New_York]

四. Temporal API 常用方法

1. 加减方法

const date = Temporal.PlainDate.from('2023-03-31');
const newDate = date.add({ days: 1 });
console.log(newDate.toString()); // 2023-04-01

2. with 方法

修改特定字段，返回新实例：

const date = Temporal.PlainDate.from('2023-10-15');
const updatedDate = date.with({ year: 1999, month: 5 });
console.log(updatedDate.toString()); // 1999-05-15

五. Temporal API 的性能与可靠性

1. 性能优化

减少不必要的时区计算和格式转换，适合高性能应用。

2. 解析规则一致

强制使用 ISO 格式，解析结果始终一致：

const date = Temporal.PlainDate.from('2023-10-15');
console.log(date.toString()); // 2023-10-15

3. 不可变性

避免意外修改原对象，提高代码可维护性：

const date = Temporal.PlainDate.from('2023-10-15');
const newDate = date.add({ days: 1 });
console.log(date.toString()); // 原始对象未变: 2023-10-15
console.log(newDate.toString()); // 新实例: 2023-10-16

六. 使用 Temporal API 时的常见错误及解决方法

1. 忘记处理夏令时

const date = Temporal.ZonedDateTime.from('2023-03-12T02:30[America/New_York]');
const adjustedDate = date.round({ smallestUnit: 'minute', roundingMode: 'floor' });
console.log(adjustedDate.toString()); // 自动调整到有效时间

2. 使用无效时区标识符

try {
  const timeZone = Temporal.TimeZone.from('Invalid/TimeZone');
} catch (error) {
  console.error('无效的时区标识符');
}

七. Temporal API 与其他替代方案比较

选择建议

• Temporal API：适合新项目及现代化日期处理场景。
• Moment.js：已弃用，不推荐新项目使用。
• date-fns：轻量级，但不支持时区。

八. 结论

Temporal API 是 JavaScript 日期时间处理的未来。通过不可变性、显式时区支持和一致解析规则，它彻底解决了传统 Date API 的痛点。对于追求现代化、高效且可靠的日期处理方式的开发者，Temporal API 是最佳选择。

原文链接: https://pieces.app/blog/javascript-temporal-api