Temporal API：告别 JavaScript Date 的混乱
Date 对象可能是最令 JavaScript 开发者头疼的 API 之一。无论是处理时区转换、格式化日期，还是计算日期差异，传统的 Date 对象总是让人感到困惑和不便。好消息是，全新的 Temporal API 正在改变这一切，它旨在解决 JavaScript 中日期和时间处理的诸多痛点。
JavaScript Date 对象的痛点
在深入了解 Temporal API 之前，我们先回顾一下使用传统 Date 对象时常遇到的问题：
- 月份从 0 开始计数：一月是 0，二月是 1，违背直觉。
- 时区处理混乱：缺乏明确的时区支持，跨时区操作困难。
- 可变性问题：Date 对象是可变的，容易引起意外副作用。
- 操作不便：缺少便捷的日期计算和比较方法。
- 格式化能力有限：需要依赖额外的库（如 moment.js、dayjs）来进行日期格式化。
这些问题促使 TC39 提出了 Temporal API，作为现代 JavaScript 的日期时间解决方案。
Temporal API：现代化的日期时间处理
Temporal API 提供了一套完整、直观且不可变的对象来处理日历日期和时钟时间。
核心特性
- 直观易用：月份从 1 开始，符合人类习惯。
- 不可变对象：所有操作都返回新实例，避免副作用。
- 明确的时区支持：内置时区处理功能。
- 功能丰富的操作方法：提供日期计算、比较和格式化方法。
- 精确的时间单位：支持从纳秒到年的精确时间单位。
支持的主要组件
| 对象 | 用途 |
|---|---|
Temporal.Now | 获取当前日期和时间 |
Temporal.PlainDate | 处理不含时间的日历日期 |
Temporal.PlainTime | 处理不含日期的时钟时间 |
Temporal.PlainDateTime | 处理不含时区的日期和时间 |
Temporal.ZonedDateTime | 处理带有时区的日期和时间 |
Temporal.Duration | 表示时间段 |
Temporal.Instant | 表示时间轴上的精确时刻 |
实际应用示例
1. 创建日期和时间
// 当前日期
const today = Temporal.Now.plainDateISO();
console.log(today.toString()); // 输出：2025-04-16
// 特定日期
const birthday = Temporal.PlainDate.from({ year: 2025, month: 7, day: 15 });
console.log(birthday.toString()); // 输出：2025-07-15
// 日期时间
const meeting = Temporal.PlainDateTime.from({
year: 2025, month: 4, day: 20,
hour: 14, minute: 30
});
console.log(meeting.toString()); // 输出：2025-04-20T14:30:00
2. 日期计算
const start = Temporal.PlainDate.from('2025-04-16');
const end = Temporal.PlainDate.from('2025-04-20');
// 计算天数差
const days = end.since(start).days;
console.log(days); // 输出：4
3. 时区处理
const zoned = Temporal.ZonedDateTime.from({
year: 2025, month: 4, day: 16,
hour: 10, minute: 0,
timeZone: 'Asia/Shanghai'
});
console.log(zoned.toString());
// 输出：2025-04-16T10:00:00+08:00[Asia/Shanghai]
4. 日期格式化
const date = Temporal.PlainDate.from('2025-04-16');
console.log(date.toLocaleString('zh-CN', { dateStyle: 'full' }));
// 输出：2025年4月16日星期三
Temporal API 与 Date 对象对比
| 功能 | Date 对象 | Temporal API |
|---|---|---|
| 月份表示 | 0-11（一月是0） | 1-12（一月是1） |
| 可变性 | 可变 | 不可变 |
| 时区支持 | 有限 | 完整 |
| 日期计算 | 手动计算 | 内置方法 |
| 格式化 | 有限 | 强大且灵活 |
| 解析能力 | 不稳定 | 稳定可靠 |
浏览器支持与兼容性
截至 2025 年 4 月，Temporal API 已经在主流浏览器中得到支持，但仍在持续发展阶段。
若需在较旧浏览器中使用，可以通过 polyfill：
// 使用 polyfill
import { Temporal } from '@js-temporal/polyfill';
Temporal API 的到来，让 JavaScript 日期和时间处理变得直观、强大且安全。开发者再也不需要忍受 Date 对象的混乱，同时也能写出更可维护和健壮的代码。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>Date vs Temporal API 对比示例</title>
<style>
body { font-family: "Microsoft YaHei", sans-serif; padding: 20px; background: #f5f5f5; }
h2 { color: #2c3e50; }
.section { background: #fff; padding: 15px; margin-bottom: 20px; border-radius: 8px; box-shadow: 0 2px 6px rgba(0,0,0,0.1); }
pre { background: #f0f0f0; padding: 10px; border-radius: 5px; overflow-x: auto; }
</style>
</head>
<body>
<h1>JavaScript Date vs Temporal API 对比示例</h1>
<div class="section">
<h2>1. 当前日期和时间</h2>
<pre id="currentDate"></pre>
</div>
<div class="section">
<h2>2. 日期计算</h2>
<pre id="dateCalc"></pre>
</div>
<div class="section">
<h2>3. 时区处理</h2>
<pre id="timezone"></pre>
</div>
<div class="section">
<h2>4. 日期格式化</h2>
<pre id="format"></pre>
</div>
<script type="module">
import { Temporal } from 'https://cdn.jsdelivr.net/npm/@js-temporal/polyfill/dist/index.mjs';
// 1. 当前日期和时间
const nowDate = new Date();
const nowTemporal = Temporal.Now.plainDateTimeISO();
document.getElementById('currentDate').textContent =
`Date: ${nowDate.toString()}
Temporal: ${nowTemporal.toString()}`;
// 2. 日期计算
const startDate = new Date('2025-04-16');
const endDate = new Date('2025-04-20');
const diffDate = Math.floor((endDate - startDate) / (1000*60*60*24)); // 天数差
const startTemporal = Temporal.PlainDate.from('2025-04-16');
const endTemporal = Temporal.PlainDate.from('2025-04-20');
const diffTemporal = endTemporal.since(startTemporal).days;
document.getElementById('dateCalc').textContent =
`Date 计算天数差: ${diffDate} 天
Temporal 计算天数差: ${diffTemporal} 天`;
// 3. 时区处理
const tzDate = new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Tokyo' });
const tzTemporal = Temporal.ZonedDateTime.from({
year: 2025, month: 4, day: 16,
hour: 10, minute: 0,
timeZone: 'Asia/Tokyo'
});
document.getElementById('timezone').textContent =
`Date 时区: ${tzDate}
Temporal 时区: ${tzTemporal.toString()}`;
// 4. 日期格式化
const formatDate = nowDate.toLocaleDateString('zh-CN', { weekday: 'long', year:'numeric', month:'long', day:'numeric' });
const formatTemporal = nowTemporal.toLocaleString('zh-CN', { dateStyle: 'full', timeStyle: 'medium' });
document.getElementById('format').textContent =
`Date 格式化: ${formatDate}
Temporal 格式化: ${formatTemporal}`;
</script>
</body>
</html>