发布于 由admin

JS `Temporal API` (Stage 3) 与现有日期库 (`moment`, `date-fns`) 的对比与迁移

各位观众，掌声欢迎！今天咱们不聊别的，就来扒一扒这 JavaScript 日期界的新贵 —— Temporal API，看看它能不能把咱们常用的 Moment.js 和 date-fns 给拍在沙滩上，以及如果真要换，该怎么优雅地搬家。

开场白：时间都去哪儿了？（以及为什么我们需要Temporal）

话说，咱们写 JavaScript 代码，跟时间打交道是家常便饭。但 JavaScript 内置的 Date 对象，那可真是个让人一言难尽的东西。设计上的各种缺陷，导致各种奇奇怪怪的问题，简直是程序员的噩梦。

  • 月份从 0 开始： 1 月是 0，2 月是 1… 每次都得小心翼翼地加 1 减 1，生怕搞错。
  • API 混乱： getDate() 获取日期，getDay() 获取星期几… 命名不统一，记起来费劲。
  • 时区处理困难： 处理时区简直就是一场噩梦，各种 offset，各种 DST，头都大了。
  • 不可变性缺失： Date 对象是可变的，一不小心就改了原始值，调试起来简直要崩溃。

所以，就有了 Moment.js 和 date-fns 这些库来拯救我们。它们提供了更友好、更强大的 API，让日期处理变得轻松愉快。

但是！它们也有缺点。Moment.js 体积庞大，date-fns 模块化虽然好，但 API 学习曲线还是有的。而且，它们终究是第三方库，性能上总归不如原生 API。

这时候，Temporal API 就带着光环出现了。它是 TC39 委员会（就是制定 JavaScript 规范的那个组织）官方推出的日期时间 API，旨在解决 Date 对象的种种问题，并提供一套更现代、更易用、更强大的日期时间处理方案。

第一部分：Temporal API 的闪光点

Temporal API 吸收了 Moment.js 和 date-fns 的优点，并进行了改进。它主要有以下几个亮点：

  1. 不可变性 (Immutability)： Temporal 对象是不可变的。对 Temporal 对象的操作会返回一个新的 Temporal 对象，而不会修改原始对象。这避免了意外修改原始值的问题，让代码更可预测。

    const now = Temporal.Now.instant(); //获取当前时间戳
const later = now.add({ hours: 1 }); // 创建一个新的 Instant 对象，表示 1 小时后
console.log(now.toString()); // 输出原始时间戳
console.log(later.toString()); // 输出 1 小时后的时间戳

  2. 清晰的 API 设计： Temporal API 的命名非常清晰，易于理解。例如，Temporal.PlainDate 表示一个没有时区信息的日期，Temporal.ZonedDateTime 表示一个带时区信息的日期时间。

  3. 时区支持： Temporal API 提供了强大的时区支持，可以轻松处理各种时区转换和夏令时问题。

  4. 闰秒支持： Temporal API 考虑了闰秒，这在金融和科学等领域非常重要。

  5. 标准化： Temporal API 是 JavaScript 的官方标准，这意味着它将得到所有主流浏览器的支持，无需担心兼容性问题。

  6. 类型安全： Temporal API 的类型定义非常完善，可以与 TypeScript 等静态类型语言很好地配合使用，提高代码的健壮性。

第二部分：Temporal API 的核心概念

Temporal API 引入了一些新的概念，理解这些概念是掌握 Temporal API 的关键。

  • Temporal.Instant： 表示时间轴上的一个瞬间，类似于 Unix 时间戳，但精度更高。

  • Temporal.PlainDate： 表示一个没有时区信息的日期，例如 "2023-10-27"。

  • Temporal.PlainTime： 表示一个没有时区信息的时间，例如 "10:30:00"。

  • Temporal.PlainDateTime： 表示一个没有时区信息的日期和时间，例如 "2023-10-27T10:30:00"。

  • Temporal.ZonedDateTime： 表示一个带时区信息的日期和时间，例如 "2023-10-27T10:30:00+08:00[Asia/Shanghai]"。

  • Temporal.PlainYearMonth： 表示一个年和月，例如 "2023-10"。

  • Temporal.PlainMonthDay： 表示一个月和日，例如 "10-27"。

  • Temporal.Duration： 表示一段时间的长度，例如 "P1Y2M3DT4H5M6S" (1 年 2 个月 3 天 4 小时 5 分 6 秒)。

  • Temporal.TimeZone： 表示一个时区，例如 "Asia/Shanghai"。

  • Temporal.Calendar： 表示一个日历系统，例如 "iso8601"。

第三部分：Temporal API 的基本用法

咱们来看一些 Temporal API 的基本用法，感受一下它的魅力。

  1. 创建 Temporal 对象

    • Temporal.Now： 获取当前时间。

      const nowInstant = Temporal.Now.instant(); // 获取当前 Instant
const nowZonedDateTime = Temporal.Now.zonedDateTimeISO(); // 获取当前 ZonedDateTime，使用 ISO 8601 日历和系统时区
const nowPlainDate = Temporal.Now.plainDateISO(); // 获取当前 PlainDate，使用 ISO 8601 日历

    • Temporal.Instant.from(string)： 从字符串创建 Instant 对象。

      const instant = Temporal.Instant.from("2023-10-27T10:30:00Z");

    • Temporal.PlainDate.from(string)： 从字符串创建 PlainDate 对象。

      const plainDate = Temporal.PlainDate.from("2023-10-27");

    • Temporal.PlainDateTime.from(string)： 从字符串创建 PlainDateTime 对象。

      const plainDateTime = Temporal.PlainDateTime.from("2023-10-27T10:30:00");

    • Temporal.ZonedDateTime.from(string)： 从字符串创建 ZonedDateTime 对象。

      const zonedDateTime = Temporal.ZonedDateTime.from("2023-10-27T10:30:00+08:00[Asia/Shanghai]");

    • Temporal.PlainDate.from(object)： 从对象创建 PlainDate 对象。

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

  2. 获取 Temporal 对象的属性

    const plainDate = Temporal.PlainDate.from("2023-10-27");
console.log(plainDate.year); // 2023
console.log(plainDate.month); // 10
console.log(plainDate.day); // 27
console.log(plainDate.dayOfWeek); // 5 (星期五)

  3. Temporal 对象的加减操作

    const plainDate = Temporal.PlainDate.from("2023-10-27");
const tomorrow = plainDate.add({ days: 1 }); // 加一天
const yesterday = plainDate.subtract({ days: 1 }); // 减一天
console.log(tomorrow.toString()); // 2023-10-28
console.log(yesterday.toString()); // 2023-10-26

  4. Temporal 对象的比较

    const date1 = Temporal.PlainDate.from("2023-10-27");
const date2 = Temporal.PlainDate.from("2023-10-28");
console.log(date1.equals(date2)); // false
console.log(date1.lessThan(date2)); // true
console.log(date1.greaterThan(date2)); // false

  5. Temporal 对象的格式化

    Temporal API 本身没有提供格式化方法，但可以使用 Intl.DateTimeFormat 对象进行格式化。

    const plainDate = Temporal.PlainDate.from("2023-10-27");
const formatter = new Intl.DateTimeFormat("zh-CN", {
    year: "numeric",
    month: "long",
    day: "numeric",
});
console.log(formatter.format(plainDate.toJSDate())); // 2023年10月27日

    或者使用Temporal.Now.zonedDateTimeISO().toLocaleString('zh-CN', { dateStyle: 'full', timeStyle: 'long' })

  6. 时区处理

    const zonedDateTime = Temporal.ZonedDateTime.from("2023-10-27T10:30:00+08:00[Asia/Shanghai]");
const losAngelesTime = zonedDateTime.withTimeZone("America/Los_Angeles");
console.log(losAngelesTime.toString()); // 2023-10-26T19:30:00-07:00[America/Los_Angeles]

第四部分：Moment.js 和 date-fns 的迁移策略

好了，了解了 Temporal API 的基本用法，咱们来聊聊如何从 Moment.js 和 date-fns 迁移到 Temporal API。

迁移不是一蹴而就的，需要分步骤进行。

  1. 评估现有代码： 首先，需要评估现有代码中使用了多少 Moment.js 或 date-fns 的 API，以及这些 API 的复杂程度。

  2. 逐步替换： 不要试图一次性替换所有代码。可以先从简单的日期格式化开始，逐步替换更复杂的日期计算。

  3. 编写测试： 在替换代码的同时，务必编写测试用例，确保替换后的代码功能正确。

  4. 封装兼容层： 如果需要同时支持新旧代码，可以编写一个兼容层，将 Temporal API 封装成 Moment.js 或 date-fns 的 API，方便现有代码调用。

下面是一些具体的迁移示例：

1. Moment.js 迁移到 Temporal API

Moment.js Temporal API 备注
moment() Temporal.Now.zonedDateTimeISO() (获取当前时间，带时区信息)
Temporal.Now.plainDateISO() (获取当前日期，不带时区信息)		 Moment() 创建的是可变对象，而 Temporal 创建的是不可变对象。
moment(string) Temporal.PlainDateTime.from(string) (不带时区信息)
Temporal.ZonedDateTime.from(string) (带时区信息)		 需要注意字符串格式。
moment(number) Temporal.Instant.fromEpochMilliseconds(number) Moment.js 接受毫秒时间戳，Temporal API 使用 fromEpochMilliseconds 方法。
moment().format('YYYY-MM-DD') Temporal.Now.zonedDateTimeISO().toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit' }) Temporal API 本身没有格式化方法，需要使用 Intl.DateTimeFormat 对象。
moment().add(7, 'days') Temporal.Now.plainDateISO().add({ days: 7 }) Temporal API 的加减操作使用 add 和 subtract 方法，参数是一个对象，指定要加减的时间单位和数量。
moment().diff(moment(), 'days') Temporal.Now.plainDateISO().until(Temporal.PlainDate.from("2024-01-01"), {largestUnit: 'day'}).days 使用 until 或 since 方法计算两个 Temporal 对象之间的差值。
moment().isBefore(moment()) Temporal.Now.plainDateISO().lessThan(Temporal.PlainDate.from("2024-01-01")) 使用 lessThan, greaterThan, equals 方法进行比较。
moment().utcOffset() Temporal.Now.zonedDateTimeISO().timeZone.getOffsetStringFor(Temporal.Now.instant()) Temporal API 使用 timeZone 属性和 getOffsetStringFor 方法获取时区偏移量。
moment.duration(1, 'days').asSeconds() Temporal.Duration.from({ days: 1 }).total({ unit: 'second' }) Temporal API 使用 Temporal.Duration 对象表示一段时间的长度，使用 total 方法获取总秒数。
moment().startOf('day') Temporal.Now.plainDateISO().toPlainDateTime({hour: 0, minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0})

代码示例

// Moment.js
const moment = require('moment');

const now = moment();
const formattedDate = now.format('YYYY-MM-DD');
const futureDate = now.add(7, 'days');
console.log(`Moment.js: Current date: ${formattedDate}, Future date: ${futureDate.format('YYYY-MM-DD')}`);

// Temporal API
const Temporal = globalThis.Temporal; // 需要 polyfill 支持
const nowTemporal = Temporal.Now.zonedDateTimeISO();
const formattedDateTemporal = nowTemporal.toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit' });
const futureDateTemporal = nowTemporal.add({ days: 7 });
const formattedFutureDateTemporal = futureDateTemporal.toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit' });
console.log(`Temporal API: Current date: ${formattedDateTemporal}, Future date: ${formattedFutureDateTemporal}`);

2. date-fns 迁移到 Temporal API

date-fns Temporal API 备注
new Date() Temporal.Now.zonedDateTimeISO() (获取当前时间，带时区信息)
Temporal.Now.plainDateISO() (获取当前日期，不带时区信息)		 date-fns 使用原生 Date 对象，Temporal API 使用自己的对象。
parseISO(string) Temporal.PlainDateTime.from(string) (不带时区信息)
Temporal.ZonedDateTime.from(string) (带时区信息)		 需要注意字符串格式。
format(date, 'yyyy-MM-dd') Temporal.Now.zonedDateTimeISO().toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit' }) Temporal API 本身没有格式化方法，需要使用 Intl.DateTimeFormat 对象。
addDays(date, 7) Temporal.Now.plainDateISO().add({ days: 7 }) Temporal API 的加减操作使用 add 和 subtract 方法，参数是一个对象，指定要加减的时间单位和数量。
differenceInDays(date1, date2) Temporal.Now.plainDateISO().until(Temporal.PlainDate.from("2024-01-01"), {largestUnit: 'day'}).days 使用 until 或 since 方法计算两个 Temporal 对象之间的差值。
isBefore(date1, date2) Temporal.Now.plainDateISO().lessThan(Temporal.PlainDate.from("2024-01-01")) 使用 lessThan, greaterThan, equals 方法进行比较。
utcToZonedTime(date, timezone) Temporal.Instant.fromEpochMilliseconds(date.getTime()).toZonedDateTimeISO(timezone) Temporal API 需要先将date转化为Instant，然后通过toZonedDateTimeISO转化为目标时区。
sub(date, {days: 1, hours: 2}) Temporal.Now.plainDateISO().subtract({ days: 1, hours: 2 }) Temporal API 使用 Temporal.Duration 对象表示一段时间的长度，使用 total 方法获取总秒数。
startOfDay(date) Temporal.PlainDate.from(date).toPlainDateTime({ hour: 0, minute: 0, second: 0 })

代码示例

// date-fns
const { format, addDays, parseISO } = require('date-fns');

const now = new Date();
const formattedDate = format(now, 'yyyy-MM-dd');
const futureDate = addDays(now, 7);
console.log(`date-fns: Current date: ${formattedDate}, Future date: ${format(futureDate, 'yyyy-MM-dd')}`);

// Temporal API
const Temporal = globalThis.Temporal; // 需要 polyfill 支持
const nowTemporal = Temporal.Now.zonedDateTimeISO();
const formattedDateTemporal = nowTemporal.toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit' });
const futureDateTemporal = nowTemporal.add({ days: 7 });
const formattedFutureDateTemporal = futureDateTemporal.toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit' });
console.log(`Temporal API: Current date: ${formattedDateTemporal}, Future date: ${formattedFutureDateTemporal}`);

第五部分：Temporal API 的现状和未来

Temporal API 目前还处于 Stage 3 阶段，这意味着它还没有正式成为 JavaScript 的标准。但是，已经有一些浏览器和 Node.js 环境支持 Temporal API，可以通过 polyfill 来在不支持的环境中使用。

Temporal API 的未来是光明的。随着越来越多的浏览器和 Node.js 环境支持 Temporal API，它将逐渐取代 Moment.js 和 date-fns，成为 JavaScript 日期时间处理的首选方案。

第六部分：注意事项

  1. Polyfill： 在正式成为标准之前，需要在不支持 Temporal API 的环境中引入 polyfill。可以使用 temporal-polyfill 这个库。

  2. 兼容性： 在迁移过程中，需要考虑兼容性问题。如果需要同时支持新旧代码，可以编写一个兼容层。

  3. 学习成本： Temporal API 引入了一些新的概念，需要一定的学习成本。

  4. 格式化： Temporal API 本身没有提供格式化方法，需要使用 Intl.DateTimeFormat 对象。

总结：拥抱未来，拥抱 Temporal API

Temporal API 是 JavaScript 日期时间处理的未来。它解决了 Date 对象的种种问题，并提供了一套更现代、更易用、更强大的日期时间处理方案。虽然迁移到 Temporal API 需要一定的成本，但从长远来看，它是值得的。

所以，各位观众，让我们一起拥抱未来，拥抱 Temporal API 吧！

Q&A 环节

（此处省略提问和解答环节，大家可以自行脑补一些常见问题，例如 "Temporal API 的性能如何？" "Temporal API 的学习曲线陡峭吗？" 等等。）

谢谢大家！今天的讲座就到这里，我们下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注