JavaScript内核与高级编程之：`JavaScript`的`Temporal API`：其在日期时间处理中的新提案。

各位观众老爷，大家好！今天咱们来聊聊 JavaScript 里一个比较新的玩意儿，叫做 Temporal API。这家伙，简单来说，就是为了解决 JavaScript 日期时间处理的“老大难”问题而生的。

为啥要搞个Temporal API？JavaScript的Date对象不好使吗？

你问得好！JavaScript 内置的 Date 对象，说实话，问题真的不少。我先给大家列举几个“罪状”：

• 可变性（Mutability）： Date 对象是可变的，这意味着你一个不小心，就能把日期给改了，而且还没法追溯。
• 时区处理混乱： Date 对象的时区处理方式让人摸不着头脑，经常会遇到各种时区转换的坑。
• API设计糟糕： Date 对象的 API 设计简直是灾难，各种 getYear()、getMonth() 这种过时的 API 还在，而且索引从 0 开始，让人防不胜防。
• 缺乏明确的日期和时间类型： Date 对象既包含日期，又包含时间，有时候你只想处理日期，有时候只想处理时间，它就显得很笨重。
• 不支持非公历日历： Date 对象只支持公历（格里高利历），不支持农历、伊斯兰历等其他日历系统。

正是因为 Date 对象有这么多问题，所以社区一直呼吁要搞一个新的日期时间 API。于是，Temporal API 就应运而生。

Temporal API 是个啥？

Temporal API 是一套全新的 JavaScript 日期时间 API，旨在替代 Date 对象，解决它的各种问题。它主要有以下几个特点：

• 不可变性（Immutability）： Temporal API 中的日期时间对象是不可变的，这意味着你对它们进行任何操作，都会返回一个新的对象，而不会修改原来的对象。
• 明确的类型： Temporal API 提供了多种明确的类型，比如 Temporal.PlainDate（只包含日期）、Temporal.PlainTime（只包含时间）、Temporal.PlainDateTime（包含日期和时间）、Temporal.ZonedDateTime（带时区的日期时间）等等。
• 现代化的 API： Temporal API 采用现代化的 API 设计，易于理解和使用。
• 时区支持： Temporal API 提供了强大的时区支持，可以方便地进行时区转换。
• 日历支持： Temporal API 支持多种日历系统，可以处理非公历日期。

Temporal API 的主要类型

咱们先来了解一下 Temporal API 中最常用的几个类型：

类型	描述
Temporal.PlainDate	只包含日期的类型，不包含时间和时区信息。
Temporal.PlainTime	只包含时间的类型，不包含日期和时区信息。
Temporal.PlainDateTime	包含日期和时间的类型，不包含时区信息。
Temporal.ZonedDateTime	包含日期、时间和时区信息的类型。
Temporal.Instant	时间轴上的一个瞬间，以 UTC 时间表示。
Temporal.TimeZone	时区信息。
Temporal.Duration	时间段，表示两个日期时间之间的差值，比如“3天”、“2小时”等。
Temporal.Calendar	日历系统，比如公历、农历等。

Temporal API 的基本用法

接下来，咱们通过一些代码示例来演示 Temporal API 的基本用法。

1. 创建日期时间对象

// 创建一个 PlainDate 对象
const plainDate = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27 });
console.log(plainDate.toString()); // 输出：2023-10-27

// 创建一个 PlainTime 对象
const plainTime = Temporal.PlainTime.from({ hour: 10, minute: 30, second: 0 });
console.log(plainTime.toString()); // 输出：10:30:00

// 创建一个 PlainDateTime 对象
const plainDateTime = Temporal.PlainDateTime.from({ year: 2023, month: 10, day: 27, hour: 10, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // 输出：2023-10-27T10:30:00

// 创建一个 ZonedDateTime 对象
const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2023, month: 10, day: 27, hour: 10, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // 输出：2023-10-27T10:30:00-07:00[America/Los_Angeles]

// 获取当前日期和时间
const now = Temporal.Now.plainDateTimeISO();
console.log(now.toString());

// 获取当前带时区的日期和时间
const nowZoned = Temporal.Now.zonedDateTimeISO('Asia/Shanghai');
console.log(nowZoned.toString());

2. 获取日期时间信息

const plainDate = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27 });

console.log(plainDate.year);   // 输出：2023
console.log(plainDate.month);  // 输出：10
console.log(plainDate.day);    // 输出：27
console.log(plainDate.dayOfWeek); // 输出：5 (星期五)
console.log(plainDate.dayOfYear); // 输出：300
console.log(plainDate.daysInMonth); // 输出：31
console.log(plainDate.daysInYear); // 输出：365
console.log(plainDate.monthCode); // 输出：M10
console.log(plainDate.isLeapYear); // 输出：false

const plainTime = Temporal.PlainTime.from({ hour: 10, minute: 30, second: 0 });

console.log(plainTime.hour);   // 输出：10
console.log(plainTime.minute);  // 输出：30
console.log(plainTime.second);  // 输出：0
console.log(plainTime.millisecond); // 输出：0
console.log(plainTime.microsecond); // 输出：0
console.log(plainTime.nanosecond); // 输出：0

3. 修改日期时间对象

const plainDate = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27 });

// 修改年份
const newPlainDate = plainDate.with({ year: 2024 });
console.log(newPlainDate.toString()); // 输出：2024-10-27
console.log(plainDate.toString()); // 输出：2023-10-27 （原始对象未被修改）

// 增加天数
const laterDate = plainDate.add({ days: 5 });
console.log(laterDate.toString()); // 输出：2023-11-01

// 减少月份
const earlierDate = plainDate.subtract({ months: 2 });
console.log(earlierDate.toString()); // 输出：2023-08-27

4. 日期时间比较

const date1 = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27 });
const date2 = Temporal.PlainDate.from({ year: 2023, month: 11, day: 15 });

// 比较日期
console.log(Temporal.PlainDate.compare(date1, date2)); // 输出：-1 (date1 < date2)

// 判断是否相等
console.log(date1.equals(date2)); // 输出：false

// 比较大小
console.log(date1 < date2); // false (Temporal对象不能直接用< >比较，需使用compare)

5. 日期时间格式化

const plainDate = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27 });

// 使用 toLocaleString 格式化日期
console.log(plainDate.toLocaleString('zh-CN', { dateStyle: 'full' })); // 输出：2023年10月27日 星期五
console.log(plainDate.toLocaleString('en-US', { dateStyle: 'long' })); // 输出：October 27, 2023

const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2023, month: 10, day: 27, hour: 10, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });

// 使用 toLocaleString 格式化带时区的日期时间
console.log(zonedDateTime.toLocaleString('zh-CN', { dateStyle: 'full', timeStyle: 'long' }));
// 输出：2023年10月27日 星期五 上午10:30:00 美国太平洋时间

6. 时区处理

const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2023, month: 10, day: 27, hour: 10, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });

// 转换为其他时区
const shanghaiTime = zonedDateTime.withTimeZone('Asia/Shanghai');
console.log(shanghaiTime.toString()); // 输出：2023-10-28T01:30:00+08:00[Asia/Shanghai]

// 获取时区信息
console.log(zonedDateTime.timeZoneId); // 输出：America/Los_Angeles

7. Duration 的使用

const date1 = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27 });
const date2 = Temporal.PlainDate.from({ year: 2023, month: 11, day: 15 });

// 计算两个日期之间的差值
const duration = date2.since(date1);
console.log(duration.toString()); // 输出：P19D (19天)

// 创建一个 Duration 对象
const duration2 = Temporal.Duration.from({ days: 5, hours: 2, minutes: 30 });
console.log(duration2.toString()); // 输出：P5DT2H30M

// 将 Duration 加到日期上
const newDate = date1.add(duration2);
console.log(newDate.toString()); // 输出：2023-11-01

8. Calendar 的使用 (简单示例)

虽然 Temporal API 的 Calendar 功能很强大，但目前还没有完全标准化，所以这里只给出一个简单的示例。

// 创建一个公历日期
const plainDate = Temporal.PlainDate.from({ year: 2023, month: 10, day: 27, calendar: 'iso8601' });
console.log(plainDate.toString());

//获取当前日历
console.log(plainDate.calendar.id); //输出：iso8601

// 注意：非 ISO 8601 日历的支持可能需要额外的库或 polyfill。

Temporal API 的优势总结

• 不可变性： 避免了日期时间对象被意外修改的风险。
• 清晰的类型系统： 提供了多种明确的类型，可以更精确地表示日期和时间。
• 现代化的 API： 易于理解和使用，减少了出错的可能性。
• 强大的时区支持： 可以方便地进行时区转换，避免了时区相关的 bug。
• 日历支持： 可以处理非公历日期，满足了更广泛的需求。

Temporal API 的现状与未来

Temporal API 目前还处于提案阶段（Stage 3），尚未被所有浏览器完全支持。不过，你可以使用 polyfill 来在不支持的浏览器中使用它。

相信在不久的将来，Temporal API 会成为 JavaScript 日期时间处理的标准，彻底取代 Date 对象，让咱们告别日期时间处理的噩梦。

写在最后

希望通过今天的讲解，大家对 Temporal API 有了一个初步的了解。虽然它现在还不是主流，但学习它绝对是有价值的。掌握了 Temporal API，你就能写出更健壮、更可靠的日期时间处理代码，避免踩各种坑。

好了，今天的讲座就到这里。感谢大家的观看！如果有什么问题，欢迎在评论区留言，我会尽力解答。下次再见！