JS `Temporal API` (Stage 3) 深入：时区、日历、精度与互操作性

咳咳，各位观众老爷们，晚上好！我是你们的老朋友，时间魔法师，今天咱们来聊聊 JavaScript 里一个还在“施工中”但潜力无限的宝贝疙瘩——Temporal API。

这玩意儿，说白了，就是 JavaScript 准备用来彻底解决日期和时间问题的终极武器。以前 Date 对象那糟心的设计，相信大家没少吐槽吧？Temporal API 就是来拯救我们的！

今天咱们不搞虚的，直接上干货，从时区、日历、精度，一直聊到怎么跟老朋友们（比如 Date 对象）打交道。

第一章：时区，你这个磨人的小妖精！

话说回来，时间这玩意儿，最麻烦的就是时区。你以为现在是北京时间晚上8点，人家纽约可能还在睡懒觉。Temporal API 终于把时区这货给安排明白了。

以前我们用 Date 对象，处理时区简直是噩梦。又是 getTimezoneOffset()，又是 toLocaleString()，一不小心就给你算错了。

Temporal API 引入了一个新的概念：Temporal.ZonedDateTime。这就是带着时区信息的时间对象。

// 获取当前时区的时间
const now = Temporal.Now.zonedDateTimeISO();
console.log(now.toString()); // 类似：2024-10-27T20:00:00.000+08:00[Asia/Shanghai]

// 指定时区创建时间
const tokyoTime = Temporal.ZonedDateTime.from({
  year: 2024,
  month: 10,
  day: 28,
  hour: 9,
  minute: 0,
  second: 0,
  timeZone: 'Asia/Tokyo'
});
console.log(tokyoTime.toString()); // 2024-10-28T09:00:00+09:00[Asia/Tokyo]

// 时区转换
const newYorkTime = tokyoTime.withTimeZone('America/New_York');
console.log(newYorkTime.toString()); // 2024-10-27T20:00:00-04:00[America/New_York]

看到没？withTimeZone() 一句话搞定时区转换，简直不要太爽！再也不用自己手动算偏移量了。

重要提示： Temporal API 使用的是 IANA 时区数据库，这个数据库会定期更新，所以你的时间总是最新的。

第二章：日历，世界那么大，我想用用不同的日历

除了时区，日历也是个大坑。全世界人民用的日历可不一样，有公历、农历、伊斯兰历等等。以前 Date 对象只能用公历，想用别的日历？自己写算法去吧！

Temporal API 引入了 Temporal.Calendar 对象，可以让你轻松使用不同的日历。

// 创建一个农历日历
const chineseCalendar = Temporal.Calendar.from('chinese');

// 创建一个使用农历日历的 Temporal.PlainDate
const chineseDate = Temporal.PlainDate.from({
  year: 2024,
  month: 9,
  day: 1,
  calendar: chineseCalendar
});

console.log(chineseDate.toString()); // 2024-09-01[chinese]

// 获取农历日期的年份
console.log(chineseDate.year); // 2024 (注意：这不一定是公历的 2024 年)
console.log(chineseCalendar.year(chineseDate)); // 2024

// 农历日期加一个月
const nextMonth = chineseDate.add({ months: 1 }, { overflow: 'constrain' });
console.log(nextMonth.toString()); // 2024-10-01[chinese]

// 创建一个日本日历
const japaneseCalendar = Temporal.Calendar.from('japanese');
const japaneseDate = Temporal.PlainDate.from({
  year: 6, //令和6年
  month: 1,
  day: 1,
  calendar: japaneseCalendar
});
console.log(japaneseDate.toString()); // 0006-01-01[japanese]

小贴士： Temporal API 内置了一些常用的日历，比如 iso8601（默认）、gregory、chinese、japanese 等。你也可以自定义日历，不过这个比较复杂，咱们今天就不展开讲了。

第三章：精度，追求极致的完美主义者

Date 对象的精度只有毫秒级，对于一些需要更高精度的场景，就显得力不从心了。Temporal API 的精度达到了纳秒级，满足你对时间的极致追求。

// 获取当前时间的纳秒级表示
const now = Temporal.Now.instant();
console.log(now.toString()); // 类似于：2024-10-27T12:00:00.000000000Z

// 创建一个指定纳秒的时间
const preciseTime = Temporal.Instant.from('2024-10-27T12:00:00.123456789Z');
console.log(preciseTime.toString()); // 2024-10-27T12:00:00.123456789Z

// 计算两个时间点的差值
const later = Temporal.Instant.from('2024-10-27T12:00:00.123456790Z');
const duration = later.since(preciseTime);
console.log(duration.toString()); // PT0.000000001S (1纳秒)

注意： 虽然 Temporal API 的精度很高，但是实际应用中，还是要根据你的需求来选择合适的精度。毕竟，精度越高，计算量越大。

第四章：Temporal API 的基石：各种时间类型

Temporal API 引入了一堆新的时间类型，别慌，咱们一个一个来认识。

类型	描述	示例
`Temporal.Instant`	时间轴上的一个绝对时间点，始终使用 UTC 时区。	`Temporal.Instant.from('2024-10-27T12:00:00Z')`
`Temporal.ZonedDateTime`	带时区信息的时间点，可以进行时区转换。	`Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 27, hour: 20, minute: 0, timeZone: 'Asia/Shanghai' })`
`Temporal.PlainDateTime`	不带时区信息的日期和时间，用于表示一个本地时间，比如某个城市的某个时刻。	`Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 27, hour: 20, minute: 0 })`
`Temporal.PlainDate`	不带时区信息的日期，用于表示一个本地日期，比如生日、纪念日等。	`Temporal.PlainDate.from({ year: 2024, month: 10, day: 27 })`
`Temporal.PlainTime`	不带时区信息的时间，用于表示一天中的某个时刻，比如闹钟时间。	`Temporal.PlainTime.from({ hour: 20, minute: 0 })`
`Temporal.Duration`	两个时间点之间的差值，可以表示年、月、日、时、分、秒、毫秒、微秒、纳秒。	`Temporal.Duration.from({ hours: 2, minutes: 30 })`
`Temporal.YearMonth`	表示某个年份的某个月份，不带具体的日期信息。	`Temporal.YearMonth.from({ year: 2024, month: 10 })`
`Temporal.MonthDay`	表示某个月份的某一天，不带具体的年份信息。	`Temporal.MonthDay.from({ month: 10, day: 27 })`
`Temporal.Calendar`	日历系统，用于处理不同日历的日期计算。	`Temporal.Calendar.from('chinese')`
`Temporal.TimeZone`	时区信息，用于进行时区转换。	`Temporal.TimeZone.from('Asia/Shanghai')`
`Temporal.Now`	提供获取当前时间的方法。	`Temporal.Now.instant()` 获取当前的 `Temporal.Instant` 对象。`Temporal.Now.zonedDateTimeISO()` 获取当前的 `Temporal.ZonedDateTime` 对象

第五章：Temporal API 与老朋友 Date 对象的爱恨情仇

虽然 Temporal API 很强大，但是 Date 对象毕竟是 JavaScript 的“老臣”，一时半会儿还退不了休。所以，Temporal API 提供了与 Date 对象互操作的方法。

// 将 Date 对象转换为 Temporal.Instant 对象
const date = new Date();
const instant = Temporal.Instant.fromEpochMilliseconds(date.getTime());
console.log(instant.toString());

// 将 Temporal.Instant 对象转换为 Date 对象
const newDate = new Date(instant.toEpochMilliseconds());
console.log(newDate.toString());

// 将 Date 对象转换为 Temporal.ZonedDateTime 对象(需要指定时区)
const zonedDateTime = Temporal.ZonedDateTime.from({
    year: date.getFullYear(),
    month: date.getMonth() + 1, // Date的getMonth()返回0-11
    day: date.getDate(),
    hour: date.getHours(),
    minute: date.getMinutes(),
    second: date.getSeconds(),
    millisecond: date.getMilliseconds(),
    timeZone: Temporal.TimeZone.from('America/Los_Angeles')
});
console.log(zonedDateTime.toString());

// 将 Temporal.ZonedDateTime 对象转换为 Date 对象
const dateFromZonedDateTime = new Date(zonedDateTime.toInstant().toEpochMilliseconds());
console.log(dateFromZonedDateTime.toString());

温馨提示： 在新项目里，尽量使用 Temporal API，但是在与旧代码交互时，可能需要用到 Date 对象，这个时候就需要进行转换了。

第六章：Temporal API 的一些高级操作

除了上面这些基本操作，Temporal API 还提供了一些更高级的功能，比如：

格式化： 可以将 Temporal 对象格式化成各种字符串形式。
解析： 可以将字符串解析成 Temporal 对象。
比较： 可以比较两个 Temporal 对象的大小。
计算： 可以对 Temporal 对象进行加减运算。

由于时间关系，这些高级功能咱们就不一一展开讲了，感兴趣的同学可以自己去查阅 Temporal API 的文档。

第七章：Temporal API 的现状与未来

Temporal API 目前还处于 Stage 3 阶段，这意味着它还在不断完善中。虽然现在已经可以试用，但是正式发布可能还需要一段时间。

友情提示： 如果你现在想在项目中使用 Temporal API，需要使用 polyfill。

总结：

Temporal API 是 JavaScript 日期和时间处理的未来，它解决了 Date 对象存在的诸多问题，提供了更强大、更灵活、更易用的 API。虽然现在还不能完全替代 Date 对象，但是随着 Temporal API 的不断完善，相信它终将成为 JavaScript 时间处理的王者。

最后的最后，给大家留个小作业：

用 Temporal API 实现一个倒计时功能，精确到纳秒级。

好了，今天的分享就到这里，希望大家有所收获！咱们下期再见！

发表回复 取消回复

发表回复取消回复