JavaScript Temporal API实战：用原生日期处理构建跨时区日程管理器

一、Temporal 解决了 `Date` 的哪些顽疾

JavaScript 原生的 `Date` 对象设计于 1995 年，几乎原样照搬了 Java 1.0 的 `java.util.Date`，导致它从出生起就带着几个严重缺陷：月份从 0 开始、不可变对象缺失导致每次操作都要创建新实例、时区处理模糊（要么本地时区要么 UTC）、解析字符串行为不一致、没有独立的日期和时间类型。这些缺陷催生了 `moment.js` 等庞大的第三方库。

`Temporal` 的设计目标是成为日期时间处理的终极方案。它提供了一套不可变的、明确区分时区和无时区的类型系统，以及清晰的计算 API。最核心的几个类型包括：

• Temporal.Instant：代表一个绝对时间点（纳秒精度），类似 Unix 时间戳。
• Temporal.ZonedDateTime：带时区的日期时间，比如“2025年1月15日东京时间下午3点”。
• Temporal.PlainDate、PlainTime、PlainDateTime：无时区的日期、时间、日期时间，适合表示“圣诞节是12月25日”这种不依赖时区的概念。
• Temporal.Duration：表示一段时间长度，可精确到纳秒。

这些类型都采用不可变设计，所有方法返回新实例，避免了意外修改的副作用。下面我们通过一个具体的日程管理器来逐一上手。

二、案例：从零搭建一个跨时区的日程管理器

我们要实现的核心功能：

1. 用户可以在自己的时区创建一个事件（比如：2025年2月10日上午9点，东京时区）。
2. 事件存储时转换为 UTC 时间戳，以便在不同地区展示。
3. 另一个用户查看时，自动转换为其本地时区显示。
4. 支持计算事件持续时间、距离开始的倒计时，以及提前15分钟的提醒时间。

我们假设已经有一个基础的事件结构：

const event = {
    title: "项目评审会议",
    start: "2025-02-10T09:00:00+09:00[Asia/Tokyo]", // 创建者时区的时间
    duration: { hours: 1, minutes: 30 }
};

1. 解析创建者输入并存储为绝对时间

用户在东京时区输入一个日期和时间，我们首先创建一个带时区的 `ZonedDateTime`：

// 用户输入：日期 2025-02-10，时间 09:00，时区 Asia/Tokyo
const userDate = Temporal.PlainDate.from("2025-02-10");
const userTime = Temporal.PlainTime.from("09:00");
const userZone = Temporal.TimeZone.from("Asia/Tokyo");

// 组合成带时区的日期时间
const startZoned = userDate.toZonedDateTime({
    time: userTime,
    timeZone: userZone
});
// startZoned.toString() => "2025-02-10T09:00:00+09:00[Asia/Tokyo]"

存储时我们希望转换为 UTC 的 `Instant`，这样无论用户在哪里查看，都能准确还原：

const startInstant = startZoned.toInstant();
// startInstant.toString() => "2025-02-10T00:00:00Z"（注意东京比UTC快9小时）

这个 `startInstant` 就是事件的绝对发生时刻，可以存入数据库。

2. 为不同时区的用户展示时间

伦敦的同事打开应用时，我们需要从 `startInstant` 转换回 `Asia/London` 时区：

const londonZone = Temporal.TimeZone.from("Europe/London");
const startInLondon = startInstant.toZonedDateTimeISO(londonZone);
// startInLondon.toString() => "2025-02-10T00:00:00+00:00[Europe/London]"
// 伦敦显示为午夜零点，与东京上午9点恰好吻合

接着我们可以用 `toPlainDate()` 和 `toPlainTime()` 拿到纯日期和时间用于界面渲染：

const displayDate = startInLondon.toPlainDate(); // 2025-02-10
const displayTime = startInLondon.toPlainTime(); // 00:00:00

3. 计算持续时间和结束时间

事件的时长用一个 `Temporal.Duration` 对象表示。我们可以直接在 `ZonedDateTime` 上加上 `Duration` 得到结束时间：

const duration = Temporal.Duration.from({ hours: 1, minutes: 30 });
const endZoned = startZoned.add(duration);
// endZoned.toString() => "2025-02-10T10:30:00+09:00[Asia/Tokyo]"

在伦敦视角下同样可以得到正确的结束时间：

const endInLondon = endZoned.withTimeZone(londonZone);
// => "2025-02-10T01:30:00+00:00[Europe/London]"

要计算两个时间点之间的精确 `Duration`，可以用 `until` 方法：

const length = startZoned.until(endZoned);
// length.toString() => "PT1H30M"

4. 倒计时与提醒功能

假设当前时刻是 `Temporal.Now.zonedDateTimeISO(userZone)`，我们可以计算距离事件开始的剩余时间：

const now = Temporal.Now.zonedDateTimeISO(userZone);
const timeUntilStart = now.until(startZoned);
// timeUntilStart 可能是负值（事件已过）或正值

// 提取剩余小时和分钟显示
const hoursLeft = timeUntilStart.hours;
const minutesLeft = timeUntilStart.minutes;

如果需要在开始前15分钟触发提醒，可以计算出提醒的绝对时刻：

const reminderOffset = Temporal.Duration.from({ minutes: 15 });
const reminderInstant = startInstant.subtract(reminderOffset);

同样可以在用户本地时区展示提醒时间：

const reminderZoned = reminderInstant.toZonedDateTimeISO(userZone);
// 用 reminderZoned.toPlainTime() 显示具体时间

5. 重复事件的高级处理

对于每周重复的会议，`Temporal` 没有内置的重复规则解析，但我们可以用 `add` 方法和 `Duration` 来生成后续事件。比如每周三上午9点重复：

let nextEvent = startZoned;
const oneWeek = Temporal.Duration.from({ weeks: 1 });
for (let i = 0; i < 10; i++) {
    console.log(nextEvent.toPlainDate().toString());
    nextEvent = nextEvent.add(oneWeek);
}

如果需要处理更复杂的规则（如每月最后一个周五），可以结合 `Temporal.PlainDate` 的 `with` 方法和 `daysInMonth` 等属性手动计算。

三、与现有日期库的对比与迁移建议

相比 `moment.js`，`Temporal` 的优势在于它是语言内置的，不需要引入额外的包体，而且 API 更加一致和类型安全。`date-fns` 虽然轻量，但仍然无法解决时区处理的底层缺陷——它仍然依赖 `Date` 对象做运算。`Temporal` 则从根本上把时区、日期、时间拆分成独立类型，使得开发者必须明确自己的意图：到底是在处理一个绝对时间点，还是一个日历上的日期？这种强制性虽然稍微增加了代码量，但在涉及多时区业务时能避免大量隐秘的 bug。

对于已有的项目，可以渐进式地引入 `Temporal`。先在新模块中使用，与旧的 `Date` 互相转换：`Temporal.Instant.fromEpochMilliseconds(date.getTime())` 和 `new Date(instant.epochMilliseconds)` 可以充当桥梁。Node.js 18+ 和 Chrome 106+ 已经可以通过标志启用 `Temporal`，生产环境可以使用官方的 polyfill（`@js-temporal/polyfill`）来获得完整支持。

四、实践过程中遇到的一些细节

在重写日程模块时，有两点值得注意。第一是 `Duration` 的规范化问题：当你创建一个 `Duration` 对象时，它不会自动将 90 分钟转化为 1 小时 30 分钟，这种“非规范化”的表示可能在比较时造成困扰。可以用 `duration.round({ largestUnit: ‘hours’ })` 来控制输出。第二是 `ZonedDateTime` 的 `with` 方法在夏令时切换时可能出现歧义，需要显式指定 `disambiguation` 选项（’earlier’、’later’、’compatible’、’reject’）。例如在夏令时回拨的一小时里，加上 30 分钟应该选择哪个实际时间点，就必须由业务逻辑决定。

五、总结

把日程管理器从 moment 全家桶换成纯 `Temporal` 之后，打包体积减少了近 50KB（gzip 后），更重要的是代码的意图变得极其清晰：我看到 `Instant` 就知道它代表一个绝对时刻，看到 `PlainDate` 就知道它不携带时区信息。时区转换不再需要通过字符串拼接或猜测，而是由类型系统保证正确性。虽然 `Temporal` 目前还需要 polyfill 才能全平台使用，但它的设计已经足够成熟，值得所有新项目优先考虑。

如果你的下一个功能涉及到日期时间，不妨先跳过那些熟悉的工具库，试试用原生的 `Temporal` 来写。它可能会给你带来和第一次使用 `const` 和 `let` 时类似的清爽感——那些曾经需要靠第三方库和注释来避免的坑，终于可以在语言层面被消除了。