SuperAPI AI 工具集

typescript-temporal

编程与开发

查看项目

更新于 10-18 21:57

技能介绍

用途:该技能用于指导新的 TypeScript/JavaScript 代码改用 Temporal 处理日期与时间。Temporal 为不同含义的日期时间值提供各自独立的类型,从而将混用不同语义的问题暴露为编译错误,避免 Date 带来的跨日、时区偏移、星期索引错位等缺陷。

主要能力:

  1. 按语义选择类型:无时间与无时区的日历日期用 Temporal.PlainDate;月份用 PlainYearMonth;无时区的墙上时间或日期时间用 PlainTime/PlainDateTime;时间点用 Temporal.Instant;需要在某地展示或分桶的时间点用带显式 IANA 时区的 ZonedDateTime;时长用 Temporal.Duration。
  2. 在边界处一次性将时间戳转换为具名时区下的日期,例如用 Temporal.Instant.fromEpochMilliseconds(Date.now()).toZonedDateTimeISO(tz).toPlainDate() 建立统一的 today 入口;显式传时区,因为无参数的 Temporal.Now.plainDateISO() 使用宿主时区,服务器与 CI 通常为 UTC,未知时区 ID 会抛出 RangeError。
  3. 将日历日期保留在 Date 之外:避免“UTC 午夜 Date”模式被单个本地 getter 误读导致日期回退一天。
  4. 存储与传输使用 ISO 8601 字符串,在边界用 Temporal.<Type>.from(str) 解析、用 .toString() 输出,JSON.stringify 经 toJSON 产生相同字符串;字符串形式的不可能日期会抛错,属性包形式默认会截断(如 2 月 30 日变为 2 月 28 日),验证用户输入时应传 { overflow: "reject" }。
  5. 与旧 Date 和库互操作:date.toTemporalInstant()、new Date(instant.epochMilliseconds)、Temporal.Instant.fromEpochMilliseconds(ms)。
  6. 从 Date 迁移的对照习惯:getDay 从 0=周日改为 dayOfWeek 从 1=周一到 7=周日(周末为 d.dayOfWeek >= 6);getMonth 从 0 基改为 month 从 1 基;比较用 Temporal.PlainDate.compare(a, b) 或 a.until(b),<、- 和字符串拼接会因 valueOf 抛错而抛 TypeError;相等用 a.equals(b);add 返回新值而非修改原值;1 月 31 日加一个月得到 2 月 28 日;模板字符串调用 toString() 是安全的。

使用方式:在支持原生 Temporal 的运行时直接用 node -p 'typeof Temporal' 检查;用 bunx tsc --noEmit 检查类型;用 TZ=America/New_York bun test 复现时区缺陷;可用 rg 搜索 toISOString().slice(0,10)/split('T')、new Date(、Date.now()、moment/date-fns/dayjs/luxon 导入以及 getDay/getDate/getMonth/getFullYear 调用等待替换模式。

测试注意:固定测试时钟只有被假定时器库伪造时才会作用于 Temporal.Now。@sinonjs/fake-timers 自 15.4.0 起支持伪造 Temporal.Now.*;Vitest 4.1.x 的 vi.useFakeTimers()+vi.setSystemTime() 只固定 Date,Vitest 5.0.0 起支持模拟 Temporal;Jest 30.5.2 的 jest.useFakeTimers({ now }) 可固定,@jest/fake-timers 30.4.0+ 要求 fake-timers ^15.4.0;Bun 1.4.2 的 setSystemTime() 可固定。显式 toFake 列表若遗漏 "Temporal" 则其仍为真实时钟。today() 入口读取 Date.now(),在所有假定时器版本下行为一致;也可注入时钟(now: () => Temporal.Instant)。bun test 默认在 UTC 下运行,除非设置 TZ,因此需在东、西两个时区下运行日期测试。

可用性:按 MDN 浏览器兼容数据,原生支持版本为 Chrome、Edge 144,Firefox 139,Safari 仅技术预览版、稳定版与 iOS 未提供,Node.js 26.0.0(更早主版本用 polyfill),Deno 2.7,Bun 1.4.0。旧目标可用 temporal-polyfill(FullCalendar,约 20 kB,存在原生 Temporal 时优先使用原生),在入口处 import "temporal-polyfill/global";MDN 也列出 @js-temporal/polyfill,其最新版本(0.5.1,2025 年 3 月)早于 Stage 4。Chrome 扩展可在 manifest 设置 "minimum_chrome_version": "144",使旧版 Chrome 显示不兼容而非报 ReferenceError。TypeScript 类型自 TypeScript 6.0 起提供,lib 加 "ESNext",或使用细粒度 "esnext.temporal" 加 "esnext.date"(用于 toTemporalInstant);TypeScript 5.x 无 Temporal 类型,使用 polyfill 时加 import "temporal-polyfill/types/global"。

限制与适用场景:新代码应使用 Temporal 而非 new Date(、Date.now()、moment、date-fns、dayjs 或 luxon,例外是接收或返回 Date 的外部 API(库签名、valueAsDate、数据库驱动),需在调用处转换并在两侧保持 Temporal。已有 Date 代码宜在因日期缺陷被触及时迁移,而非顺带全面替换。适用于日期解析、格式化与比较、计算今天、时区、时长与工作日等场景。