结论先行: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 / Edge | Chrome 144 起默认可用(2026 年 1 月) |
| Firefox | 139 起支持(2025 年 5 月) |
| Node.js | 26.0.0 默认启用;24 需 --harmony-temporal 标志 |
| Safari | 稳定版尚未支持,以官方发布为准 |
浏览器端要覆盖 Safari 用户,过渡期可以引入 @js-temporal/polyfill 或体积更小的 temporal-polyfill,用法与原生一致:
import { Temporal, Intl } from '@js-temporal/polyfill';
const d = Temporal.PlainDate.from('2026-11-20');三大核心类型:先想清楚你在处理什么时间
- Temporal.PlainDate:纯日期,不带时区。适合生日、账单日、签到日、节假日。
- Temporal.Instant:绝对时间点,本质是时间戳。适合日志、下单时间、服务端事件。
- Temporal.ZonedDateTime:带 IANA 时区的完整日期时间。适合「上海时间早上九点开会」这类跨时区业务。
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 默认收敛到目标月的最后一天,也可以显式指定溢出策略:
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 平台为例,后端接口返回的订单数据里通常带字符串日期,前端拿到后先转类型再计算,能避免时区串扰:
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 更重要。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。