跳到主要内容
api工厂
JavaScript

Temporal API 实战:取代 moment/dayjs 的日期时间新标准

api工厂资讯栏目 约 8 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行:Temporal 已经不再是「未来提案」。它于 2026 年 3 月的 TC39 会议进入 Stage 4,随 Chrome 144(2026 年 1 月)默认发布,Firefox 139 起支持,Node.js 26.0.0(2026 年 5 月 5 日发布)默认启用。对大多数项目来说,moment 可以停止引入、dayjs 的时区插件可以逐步退役;但 Safari 稳定版尚未跟进,浏览器端过渡期仍建议搭配 polyfill。本文用示例讲清 PlainDate、Instant、ZonedDateTime 三大核心类型与时区、加减运算的正确姿势。

为什么 Date 值得被替换

Date 的问题不是「难用」,而是模型缺陷:它把「日期」「时刻」「时区」塞进同一个可变对象。月份从 0 计数、字符串解析在不同引擎间不一致、setMonth 遇月底溢出、对象可被任意修改导致共享引用悄悄出错。这些坑往往上线几个月后才暴露。moment、dayjs 的长期流行,说明原生能力没把问题解决掉。Temporal 的思路是拆概念:不同的时间语义,用不同的不可变类型表达。

当前支持现状(截至 2026 年 11 月)

环境状态
TC39 提案Stage 4(2026 年 3 月会议通过),纳入 ES2026
Chrome / EdgeChrome 144 起默认可用(2026 年 1 月)
Firefox139 起支持(2025 年 5 月)
Node.js26.0.0 默认启用;24 需 --harmony-temporal 标志
Safari稳定版尚未支持,以官方发布为准

浏览器端要覆盖 Safari 用户,过渡期可以引入 @js-temporal/polyfill 或体积更小的 temporal-polyfill,用法与原生一致:

js
import { Temporal, Intl } from '@js-temporal/polyfill';
const d = Temporal.PlainDate.from('2026-11-20');

三大核心类型:先想清楚你在处理什么时间

  • Temporal.PlainDate:纯日期,不带时区。适合生日、账单日、签到日、节假日。
  • Temporal.Instant:绝对时间点,本质是时间戳。适合日志、下单时间、服务端事件。
  • Temporal.ZonedDateTime:带 IANA 时区的完整日期时间。适合「上海时间早上九点开会」这类跨时区业务。
js
const birthday = Temporal.PlainDate.from('1998-10-12');
console.log(birthday.year, birthday.month, birthday.day); // 1998 10 12

const now = Temporal.Now.instant();
console.log(now.epochMilliseconds); // 毫秒时间戳,可直接存库

const meeting = Temporal.ZonedDateTime.from(
  '2026-11-20T09:00:00[Asia/Shanghai]'
);
console.log(meeting.withTimeZone('America/New_York').toString());

注意 month 从 1 开始,终于和人类直觉一致。所有类型都是不可变的,任何运算都返回新对象,共享引用不再有被改写的风险。

加减运算与时间差:月底和夏令时不再踩坑

Date 时代「1 月 31 日加一个月」会得到 3 月 3 日这种溢出结果,Temporal 默认收敛到目标月的最后一天,也可以显式指定溢出策略:

js
const due = Temporal.PlainDate.from('2026-01-31');
console.log(due.add({ months: 1 }).toString()); // 2026-02-28
console.log(due.add({ months: 1 }, { overflow: 'reject' })); // 抛 RangeError

const start = Temporal.PlainDate.from('2026-11-01');
const end = Temporal.PlainDate.from('2026-11-20');
console.log(start.until(end, { largestUnit: 'days' }).days); // 19

带时区的加减会自动处理夏令时:ZonedDateTime 加一天是「日历意义上的一天」,而不是机械加 24 小时,这在欧美时区的定时任务里尤其重要。Duration 还支持 round、total 操作,做账期与时长统计比手写毫秒除法可靠。

从 moment / dayjs 迁移的务实路线

不建议一次性重写存量代码。更稳的做法是:接口层和表单继续传 ISO 字符串,进入业务逻辑后转成 Temporal 对象,新模块全部用 Temporal,旧模块按改动频率逐步替换。对照关系大致是:moment() 对应 Temporal.Now.zonedDateTimeISO(),format 对应 toLocaleString 或 toString,diff 对应 until/since,add/subtract 对应 add/subtract。字符串序列化直接用 toString,与 input type=date、URL、localStorage 都天然兼容。

结合业务:订单与预约场景里的日期处理

做商城或预约类应用时,「发货日」「优惠券有效期」「会员到期日」都是纯日期语义,用 PlainDate 处理最干净。以 api工厂(https://www.it120.cc/)这类开放 SaaS 平台为例,后端接口返回的订单数据里通常带字符串日期,前端拿到后先转类型再计算,能避免时区串扰:

js
import WXAPI from 'apifm-wxapi';
WXAPI.init('your-subdomain');

async function couponDaysLeft(couponId) {
  const res = await WXAPI.myCoupons({ token: 'xxx' });
  if (res.code !== 0) return null;
  const today = Temporal.Now.plainDateISO();
  return res.data.map((c) => ({
    name: c.name,
    left: today.until(Temporal.PlainDate.from(c.dateEnd)).days,
  }));
}

SDK 方法统一返回 Promise 且以 code==0 表示成功,配合 async/await 与 Temporal 的不可变对象,整条数据链路没有可变状态,调试成本明显下降。接口字段含义可在 SDK 文档(https://www.it120.cc/sdk/index.html)中核对。

小结

Temporal 的价值不在「新」,而在把时间语义标准化:纯日期、绝对时刻、带时区时间各归其位,不可变、可预测。Node.js 服务端现在就可以认真采用;浏览器端按目标用户决定原生还是 polyfill。把「你在处理哪种时间」想清楚,比背 API 更重要。

文章标签

JavaScriptTemporalES2026日期时间前端工程

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。