40+ 便捷函数速查手册：temporal-utils 让 temporal-polyfill 日期处理更顺手

40 便捷函数速查手册temporal-utils 让 temporal-polyfill 日期处理更顺手【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporaltemporal-polyfill 是 JavaScript 新一代日期对象 Temporal 的轻量级 Polyfill而它的姊妹包temporal-utils更是为日常日期处理场景准备了一套超过 40 个开箱即用的便捷函数。本文就是一份面向新手的temporal-utils 函数速查手册帮你快速掌握日期差值、取整、月初月末、周起始等高频操作让 JS 日期处理更顺手、更省心。为什么需要 temporal-utils✨Temporal 本身已经非常强大但有些高频操作写起来依然繁琐比如“取这个月的第一天”“计算两个日期相差多少天”“把日期四舍五入到最近一周”等。temporal-utils 把这些琐碎逻辑封装成一个个语义化的小函数让你一行代码搞定。它的最大亮点是保持输入类型不变传入Temporal.PlainDate就返回Temporal.PlainDate传入Temporal.ZonedDateTime就返回Temporal.ZonedDateTime完全不用手动转换非常顺手。一键安装与快速上手temporal-utils 本身不内置 Temporal 实现运行时需要一个全局的Temporal对象——这正是 temporal-polyfill 的用武之地。第一步安装依赖npm install temporal-polyfill temporal-utils第二步引入全局 Temporalimport temporal-polyfill/global import { startOfMonth, diffDays } from temporal-utils // 传入 PlainDate返回 PlainDate startOfMonth(Temporal.PlainDate.from(2024-07-20)).toString() // 2024-07-01 // 两个日期相差的天数 diffDays( Temporal.PlainDate.from(2024-07-01), Temporal.PlainDate.from(2024-07-20), ) // 19代码就这么简单下面进入函数速查总览 40 函数速查总览五大分类一图看懂分类代表函数数量核心用途字段替换 Field ReplacementwithDayOfYear/withDayOfWeek/withWeekOfYear3替换年积日、星期几、周序号差值计算 Difference HelpersdiffDays/diffMonths/diffNanoseconds10计算两日期相差的天/月/纳秒取整 Rounding HelpersroundToYear/roundToMonth/roundToWeek9四舍五入到最近的单位边界开始时间 Start Of UnitstartOfMonth/startOfWeek/startOfDay9取单位起始时刻结束时间 End Of UnitendOfMonth/endOfWeek/endOfDay9取单位最后一刻五个分类合计40 个函数加上共享类型组成了完整的便捷函数速查体系。字段替换函数Temporal 的补位选手Temporal 能读取dayOfYear、dayOfWeek、weekOfYear这些日历派生字段却不提供直接替换它们的with({...})写法。temporal-utils 的三个字段替换函数正好补上这个缺口支持PlainDate、PlainDateTime、ZonedDateTime并支持{ overflow: constrain | reject }溢出策略。import { withDayOfWeek } from temporal-utils const date Temporal.PlainDate.from(2024-02-27) // 周二 withDayOfWeek(date, 4).toString() // 2024-02-29 同一周改成周四实现见 with.ts文档见 utils/README.md。差值计算函数10 个单位随心算diff*系列覆盖从年、月、周到纳秒的10 个时间单位返回一个数值方向性明确参数交换正负号也跟着翻转。更贴心的是支持四舍五入选项比如把差值向上取整到 7 天的倍数import { diffMonths, diffDays } from temporal-utils const start Temporal.PlainDate.from(2024-02-20) const end Temporal.PlainDate.from(2024-04-10) diffMonths(start, end) // 约 1.677... diffMonths(start, end, floor) // 1 diffDays(start, end, { roundingMode: ceil, roundingIncrement: 7 }) // 56差值实现集中在 diff.ts其中diffYears与diffMonths还额外支持PlainYearMonth输入。取整函数日历单位也能四舍五入Temporal 原生.round()只覆盖天及更小单位大日历单位年、月、周则不太统一。roundTo*系列正好补齐roundToYear、roundToMonth、roundToWeek面向日常手写代码推荐使用而天及以下的小单位函数roundToDay到roundToMicrosecond被标记为 ⚠️codemod 迁移目标手写代码更推荐直接使用原生.round()。import { roundToMonth, roundToWeek } from temporal-utils const dt Temporal.PlainDateTime.from(2024-07-20T12:30:00) roundToYear(dt).toString() // 2025-01-01T00:00:00 roundToMonth(dt, floor).toString() // 2024-07-01T00:00:00 roundToWeek(dt, { roundingMode: floor }).toString() // 2024-07-15T00:00:00默认采用halfExpand舍入模式相关实现见 round.ts。开始时间函数秒取月初、周初、零点startOf*系列把更小的字段截断到单位起点共 9 个年、月、周、日、时、分、秒、毫秒、微秒。注意startOfWeek按ISO 周计算即每周从周一开始。import { startOfMonth, startOfWeek } from temporal-utils const zdt Temporal.ZonedDateTime.from(2024-07-20T12:30:00[America/New_York]) startOfMonth(zdt).toString() // 2024-07-01T00:00:00-04:00[America/New_York] startOfWeek(zdt).toString() // 2024-07-15T00:00:00-04:00[America/New_York]对于ZonedDateTime如果本地午夜恰好被时区跳变跳过Temporal 会自动解析为跳变后的第一个真实时刻无需你操心。实现见 startOf.ts。结束时间函数精确到纳秒的“最后一刻”endOf*系列与开始时间对称返回下一个单位开始前的最后可表示值日期时间类型返回单位结束前1 纳秒纯日期类型返回单位结束前 1 天PlainYearMonth的endOfYear则返回同年 12 月。import { endOfDay, endOfMonth } from temporal-utils const dt Temporal.PlainDateTime.from(2024-07-20T12:30:00) endOfDay(dt).toString() // 2024-07-20T23:59:59.999999999 endOfMonth(dt).toString() // 2024-07-31T23:59:59.999999999实现见 endOf.ts日常统计“本月最后时刻”“本周最后一刻”非常顺手。项目源码导读快速定位实现如果你想深入了解或贡献代码整个包的结构非常清晰都在 utils/ 目录下入口与导出utils/src/index.ts字段替换utils/src/with.ts差值计算utils/src/diff.ts取整逻辑utils/src/round.ts开始 / 结束时间utils/src/startOf.ts 与 utils/src/endOf.ts类型定义utils/src/utils.ts每个模块都配有同名的.test.ts测试文件如 utils/src/diff.test.ts对照测试用例理解行为是最快的学习方式。总结一张速查手册吃透 40 函数temporal-utils 用 40 个命名清晰的小函数把 temporal-polyfill 日常日期处理的重复代码压缩到一行。无论是计算差值、四舍五入还是取月初月末、周初周末都能找到对应函数且输入输出类型完全一致。如果你正在从Date迁移到Temporal强烈建议把这份函数速查手册收藏起来配合 utils/README.md 的函数参考文档你的 JS 日期处理之路会顺滑很多 【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考