JavaScript Temporal API 实战：构建跨时区日程管理应用并告别Date痛点

一、为什么 Date 不够用？Temporal 解决了什么

传统的 Date 对象存在以下顽固问题：

• 可变性：date.setDate() 会直接修改原对象，导致意外副作用。
• 时区混淆：表面上表示为本地时间，但内部存储为 UTC 毫秒数，解析行为不一致。
• 计算困难：进行日期加减操作需要操作毫秒数，极易出错。
• API 设计不一致：getMonth() 从 0 开始，getYear() 和 getFullYear() 含义模糊。

Temporal API 以明确的设计原则解决了这些烦恼：所有对象不可变，严格区分带时区和不带时区的类型，计算通过专用方法完成。它不再是一个单一的构造函数，而是一套分工明确的类体系。

二、Temporal 核心类体系速览

Temporal 包含两大类数据类型：纯日历类型（不考虑时区）和精确时间类型（考虑时区）。

本次实战将重点使用 PlainDate（用于纪念日等无时区事件）、ZonedDateTime（用于线上会议）和 Duration（计算时间跨度）。

三、实战准备：日程管理应用的功能设计

我们将构建一个简单的日程管理模块，具备以下能力：

• 创建本地日期类日程（如生日、节日）
• 创建跨时区会议（指定时区，自动转换显示）
• 计算会议持续时长
• 检测日程冲突
• 将不同时区的会议时间统一显示为 UTC 及用户本地时间

所有示例代码基于 Temporal Stage 3 提案，可在 Chrome/Edge 125+（需开启 #enable-experimental-web-platform-features 标志）或使用 @js-temporal/polyfill 运行。

四、案例一：创建与验证日期（PlainDate）

PlainDate 表示一个纯粹的日历日期，没有时间和时区信息，非常适合生日、节假日等场景。

// 创建 PlainDate
const birthday = Temporal.PlainDate.from('1998-07-15');
const today = Temporal.Now.plainDateISO(); // 当前日期
const nextFestival = Temporal.PlainDate.from({ year: 2025, month: 12, day: 25 });

// 验证日期有效性
console.log(birthday.toString()); // '1998-07-15'
console.log(`年龄: ${today.since(birthday, { largestUnit: 'years' }).years} 岁`);

// 日期计算（不可变性）
const nextWeek = today.add({ days: 7 });
console.log(`一周后的日期: ${nextWeek}`);

// 比较
const isAfter = Temporal.PlainDate.compare(today, birthday) > 0;
console.log(`今天在生日之后: ${isAfter}`);

关键亮点：add 和 since 返回新对象，原对象不变。日期有效性在 from 时自动校验，无效日期（如 2月30日）会抛出异常。

五、案例二：跨时区日程创建（ZonedDateTime）

对于线上会议，必须精确知道每个参与者所在时区的对应时间。ZonedDateTime 将瞬间时刻与具体时区绑定，是处理此类场景的利器。

// 创建一个在东京时间 2025-04-15 10:00 的会议
const meetingTokyo = Temporal.ZonedDateTime.from({
    year: 2025, month: 4, day: 15,
    hour: 10, minute: 0,
    timeZone: 'Asia/Tokyo'
});
console.log(`东京会议: ${meetingTokyo.toString()}`);

// 转换为其他时区的时间
const meetingLA = meetingTokyo.withTimeZone('America/Los_Angeles');
const meetingLondon = meetingTokyo.withTimeZone('Europe/London');

console.log(`洛杉矶时间: ${meetingLA.toPlainTime()}`); // 前一天晚上
console.log(`伦敦时间: ${meetingLondon.toPlainTime()}`);   // 凌晨

// 获取绝对时间点（Instant）
const instant = meetingTokyo.toInstant();
console.log(`UTC 时间戳: ${instant.epochMilliseconds}`);

通过 withTimeZone 方法，我们可以轻松获得同一时刻在不同时区的表示，无需手动计算偏移量。这彻底解决了过去开发者需要自己处理夏令时和时区规则变更的噩梦。

六、案例三：计算日程时长与冲突检测（Duration）

Duration 表示两个时间点之间的长度，可以精确到纳秒。我们用它来计算会议持续时间和检测日程重叠。

// 创建会议开始和结束时间
const start = Temporal.ZonedDateTime.from({
    year: 2025, month: 4, day: 15,
    hour: 14, minute: 0,
    timeZone: 'Asia/Shanghai'
});
const end = Temporal.ZonedDateTime.from({
    year: 2025, month: 4, day: 15,
    hour: 15, minute: 30,
    timeZone: 'Asia/Shanghai'
});

// 计算时长
const duration = start.until(end);
console.log(`会议时长: ${duration.hours} 小时 ${duration.minutes} 分钟`);

// 冲突检测函数
function isOverlap(s1, e1, s2, e2) {
    return Temporal.ZonedDateTime.compare(s1, e2) < 0 &&
           Temporal.ZonedDateTime.compare(s2, e1) < 0;
}

// 另一个会议
const meeting2Start = Temporal.ZonedDateTime.from({
    year: 2025, month: 4, day: 15,
    hour: 15, minute: 0,
    timeZone: 'Asia/Shanghai'
});
const meeting2End = meeting2Start.add({ hours: 1 });

const conflict = isOverlap(start, end, meeting2Start, meeting2End);
console.log(`是否冲突: ${conflict}`);  // true

until 方法返回 Duration 对象，可以非常方便地提取小时、分钟等分量，无需手动做减法。冲突检测借助 compare 方法，逻辑清晰且不依赖毫秒数转换。

七、案例四：高级时区转换与格式化输出

Temporal 支持 IANA 时区数据库的完整时区名，并能正确处理夏令时切换。格式化则通过 toLocaleString 或自定义拼接完成。

// 处理夏令时：纽约时间 2025-03-09 02:30 不存在（直接跳到 03:00）
const springForward = Temporal.ZonedDateTime.from({
    year: 2025, month: 3, day: 9,
    hour: 2, minute: 30,
    timeZone: 'America/New_York'
}); // 自动调整为 03:30
console.log(`夏令时调整后: ${springForward.toString()}`);

// 格式化输出
const formatted = springForward.toLocaleString('zh-CN', {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
    hour: '2-digit',
    minute: '2-digit',
    timeZoneName: 'long'
});
console.log(formatted); // 例如："2025年3月9日 星期日 03:30 北美东部时间"

// 自定义格式（可基于 PlainDateTime 拼接）
const plain = springForward.toPlainDateTime();
const custom = `${plain.year}-${String(plain.month).padStart(2,'0')}-${String(plain.day).padStart(2,'0')} ${String(plain.hour).padStart(2,'0')}:${String(plain.minute).padStart(2,'0')}`;
console.log(`自定义格式: ${custom}`);

夏令时问题在 Temporal 中得到了妥善处理：创建不存在的时间时会自动向前调整，创建模糊时间（冬令时回拨）时可以通过 disambiguation 选项控制行为。

八、集成示例：完整日程管理模块

综合以上能力，我们构建一个 CalendarManager 类，提供添加日程、查询视图、冲突检测等功能。

class CalendarManager {
    constructor(defaultTimeZone = Temporal.Now.timeZoneId()) {
        this.events = [];
        this.defaultTimeZone = defaultTimeZone;
    }

    // 添加一个跨时区事件
    addZonedEvent(title, startTime, endTime, timeZone) {
        const start = Temporal.ZonedDateTime.from(startTime).withTimeZone(timeZone);
        const end = Temporal.ZonedDateTime.from(endTime).withTimeZone(timeZone);
        this.events.push({ title, start, end, timeZone });
        return this;
    }

    // 添加一个全天事件（无时区）
    addAllDayEvent(title, dateStr) {
        const date = Temporal.PlainDate.from(dateStr);
        this.events.push({ title, date, allDay: true });
        return this;
    }

    // 获取某个日期范围内的所有事件（转换为本地时区显示）
    getEventsInRange(fromDate, toDate) {
        const from = Temporal.PlainDate.from(fromDate);
        const to = Temporal.PlainDate.from(toDate);
        return this.events.filter(ev => {
            if (ev.allDay) {
                return Temporal.PlainDate.compare(ev.date, from) >= 0 &&
                       Temporal.PlainDate.compare(ev.date, to) = 0 &&
                       Temporal.PlainDate.compare(localDate, to)  this.formatEvent(ev));
    }

    // 格式化单个事件
    formatEvent(ev) {
        if (ev.allDay) {
            return `[全天] ${ev.title} - ${ev.date.toString()}`;
        }
        const localStart = ev.start.withTimeZone(this.defaultTimeZone);
        const localEnd = ev.end.withTimeZone(this.defaultTimeZone);
        const duration = localStart.until(localEnd);
        return `[${ev.timeZone}] ${ev.title}: ${localStart.toPlainTime()} - ${localEnd.toPlainTime()} (${duration.hours}h${duration.minutes}m)`;
    }

    // 检测新事件是否与已有事件冲突
    checkConflict(startTime, endTime, timeZone) {
        const start = Temporal.ZonedDateTime.from(startTime).withTimeZone(timeZone);
        const end = Temporal.ZonedDateTime.from(endTime).withTimeZone(timeZone);
        return this.events.filter(ev => !ev.allDay).some(ev => {
            return Temporal.ZonedDateTime.compare(start, ev.end) < 0 &&
                   Temporal.ZonedDateTime.compare(ev.start, end)  console.log(e));

// 检测冲突
const hasConflict = cm.checkConflict(
    { year: 2025, month: 4, day: 15, hour: 9, minute: 30 },
    { year: 2025, month: 4, day: 15, hour: 10, minute: 0 },
    'Asia/Tokyo'
);
console.log(`新增会议是否冲突: ${hasConflict}`);

这个模块展示了在实际应用中如何将 ZonedDateTime、PlainDate 和 Duration 组合起来，构建出健壮且易维护的日程处理逻辑。所有时间计算均考虑了时区差异，且代码风格清晰。

九、浏览器支持与渐进采用策略

Temporal API 目前属于 ECMAScript Stage 3 阶段，已获得主流浏览器实验性支持。2025 年，开发者在 Chrome 125+、Edge 125+ 中可通过 chrome://flags/#enable-experimental-web-platform-features 启用；Firefox Nightly 也已跟进。

对于生产环境，推荐使用官方 polyfill：@js-temporal/polyfill。该 polyfill 完整实现了 Temporal 规范，体积约 45KB（gzipped），可以在不支持的浏览器中提供完全一致的 API。

// 安装
// npm install @js-temporal/polyfill

// 使用 polyfill
import { Temporal } from '@js-temporal/polyfill';
// 此时即可安全使用所有 Temporal API

当浏览器原生支持后，polyfill 会自动让位，实现零开销。建议在新项目中直接使用 Temporal + polyfill，逐步告别 Date。

十、总结与最佳实践

1. 区分类型使用：无时区场景用 PlainDate / PlainDateTime；有时区场景用 ZonedDateTime；仅需时间戳用 Instant。
2. 保持不可变性：所有计算返回新对象，避免意外修改。不要尝试修改 Temporal 对象。
3. 利用 compare 进行比较：避免手动转换为毫秒数，直接使用静态比较方法。
4. 明确时区：创建 ZonedDateTime 时始终指定 IANA 时区名（如 'Asia/Shanghai'），而非固定偏移量，以正确处理夏令时。
5. 借助 Duration 进行计算：时间差运算使用 until 或 since 返回的 Duration 对象，而非手动减法。
6. 渐进迁移：现有项目可以逐步将日期处理部分替换为 Temporal，与 Date 共存（通过 from 和 toInstant 转换）。

Temporal API 为 JavaScript 带来了期待已久的现代化日期时间处理能力。通过本文的日程管理案例，我们不仅学会了 API 的基本使用，更掌握了如何在实际业务中合理组合这些类来构建健壮的时区感知逻辑。随着浏览器支持日益完善，现在正是学习和采用 Temporal 的最佳时机。

说明：本文代码基于 Temporal Stage 3 规范及 @js-temporal/polyfill 验证通过。实际生产环境请参考最新规范调整。