date-fns 入门指南在浏览器与 Node.js 中优雅地操作 JavaScript 日期【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fnsdate-fns 是一个现代、模块化的 JavaScript 日期工具库为在浏览器与 Node.js 中处理日期提供全面、简洁且一致的工具集。本文基于 date-fns 仓库当前核心包版本为 v4.4.0的官方文档与源码讲解它的核心设计理念、安装方式、子模块体系以及最常用的函数用法读完即可在项目中快速上手。仓库核心文档与源码可分别参考 pkgs/core/docs/gettingStarted.md 与 pkgs/core/src。为什么选择 date-fnsdate-fns 的定位是“日期领域的 Lodash”它在不引入复杂抽象的前提下把日常开发中几乎所有与日期相关的操作都封装成了简单、一致的函数。从仓库根目录 README.md 的定位描述看它的核心卖点集中在以下几点200 函数覆盖各种场景从加减日期、比较日期、格式化输出到区间遍历、周/年历计算、时区处理几乎覆盖所有日常需求。模块化设计只引入你需要的那部分代码天然兼容 webpack、Browserify、Rollup 等打包工具并且支持 tree-shaking避免把整个库塞进最终产物。原生 Date 类型直接基于 JavaScript 现有的原生Date类型工作出于安全考虑不去扩展核心对象不污染原型链。不可变与纯函数所有函数都是纯函数总是返回一个新的 Date 实例绝不修改传入的参数便于预测行为与测试。100% TypeScript整个库由 TypeScript 编写并附带全新手工打磨的类型定义开箱即用的类型安全。I18n 国际化内置数十种语言 locale按需引入只打包你需要的语言。需要特别说明的是这里的“200 函数”是官方文档的表述实际数量以发布版本为准从 pkgs/core/package.json 的exports字段可以看到当前仓库为每个函数都提供了独立的子路径导出。安装与快速上手date-fns 以 npm 包形式发布。官方文档给出的安装命令如下npm install date-fns --save # 或 yarn add date-fns以 npm 安装为例仓库中pkgs/core就是实际的发布包包名为date-fns见 pkgs/core/package.json。安装完成后即可按需导入import { compareAsc, format } from date-fns; format(new Date(2014, 1, 11), yyyy-MM-dd); // 2014-02-11 const dates [ new Date(1995, 6, 2), new Date(1987, 1, 11), new Date(1989, 6, 10), ]; dates.sort(compareAsc); // [ // Wed Feb 11 1987 00:00:00, // Mon Jul 10 1989 00:00:00, // Sun Jul 02 1995 00:00:00 // ]上面的示例同时演示了两个最常用的函数format(date, formatString)按指定的格式字符串输出日期compareAsc(dateLeft, dateRight)比较两个日期可作为Array.prototype.sort的比较器直接传入实现日期数组的升序排序。从 pkgs/core/src/compareAsc/index.ts 的实现可以看到compareAsc的内部逻辑非常直观它先把两个入参统一转换成时间戳做差差值为负返回-1、为正返回1、相等返回0若差值为NaN则原样返回NaN。该行为在 pkgs/core/src/compareAsc/test.ts 中有完整的测试覆盖包括相等、早于、晚于以及数组排序四种典型场景。另一个文档中的经典示例是相对时间格式化import { formatDistance, subDays } from date-fns; formatDistance(subDays(new Date(), 3), new Date(), { addSuffix: true }); // 3 days ago这里subDays从当前时间减去 3 天formatDistance计算两个日期之间的友好距离描述addSuffix: true会在结果后追加“ago”等前后缀。值得一提的是这类描述会根据所选 locale 输出不同语言详见下文“国际化”一节。关于输入参数的类型date-fns 的绝大多数函数都接受“可被转换为 Date 的值”DateArg作为输入既可以是 Date 实例也可以是时间戳数字。所有传入的参数都会先经过内部统一的toDate转换。从 pkgs/core/src/toDate/index.ts 的实现可以看到toDate通过constructFrom完成转换Date 实例会被克隆数字被当作时间戳处理其余类型得到 Invalid Date。这也从源码层面印证了“不可变、纯函数”的设计——输入参数永远不会被修改。子模块FP 函数式编程变体date-fns 的 npm 包内还附带了一些可选功能子模块。根据 pkgs/core/docs/gettingStarted.md 的说明目前主要包括FP—— 面向函数式编程的函数变体参见 pkgs/core/src/fp 目录。子模块是嵌套包含的如果你想同时使用多个子模块功能后列的子模块已被包含在前者之中。使用子模块前同样需要先安装 npm 包然后从对应子路径导入// 主模块标准用法 import { addDays } from date-fns; // FP 变体柯里化、参数顺序更贴合函数式组合 import { addDays, format } from date-fns/fp;从 pkgs/core/package.json 的exports可以看出FP 子模块为几乎每个函数都提供了两种变体标准版如./fp/addDays和带WithOptions后缀、可传入 options 的版本如./fp/addDaysWithOptions。相应地pkgs/core/src/fp/index.ts 是这些导出的汇总入口。核心 API 速览format 与 unicode 令牌format是 date-fns 使用频率最高的函数之一它的格式字符串基于Unicode Technical Standard #35CLDR 日期字段符号表而不是 Moment.js 的自定义规则。所有支持的令牌在 pkgs/core/src/format/index.ts 的文档注释中有完整表格以下列出最常用的一部分单元令牌结果示例说明日历年份y/yy/yyyy44/44/0044四位年份建议用yyyy月份M/MM/MMM/MMMM1/01/Jan/JanuaryMMMM为完整月份名日月内d/dd1/01与D年内第几天区分日年内D/DD/DDD1/01/001需useAdditionalDayOfYearTokens选项星期几E..EEE/EEEE/EEEEEMon/Monday/M小时 [0-23]H/HH0/0024 小时制小时 [1-12]h/hh1/0112 小时制常与a连用AM/PMa..aa/aaa/aaaaAM/am/a.m.分钟m/mm0/00秒s/ss0/00注意format的令牌与 Moment.js 等库不同例如D/DD表示“年内第几天”1, 2, ..., 365, 366常被误当作“月内第几天”月内第几天应使用d/dd1, 2, ..., 31。YY/YYYY表示“本地周编号年份”44, 01, 00, 17常被误当作日历年份日历年份应使用yy/yyyy。为防止这种混淆format与parse默认会拒绝D、DD、YY、YYYY四个令牌除非显式传入对应选项详见 pkgs/core/docs/unicodeTokens.md// ❌ 错误把 YYYY/DD 当成年月日用 format(new Date(), YYYY-MM-DD); // ✅ 正确 format(new Date(), yyyy-MM-dd); // 2018-10-10 // ✅ 显式启用额外令牌 format(new Date(), D, { useAdditionalDayOfYearTokens: true }); // 283 parse(3651987, DDYYYY, new Date(), { useAdditionalDayOfYearTokens: true, useAdditionalWeekYearTokens: true, }); // Wed Dec 31 1986 ...此外格式字符串中被单引号...包裹的字符会被当作字面量原样输出两个连续单引号表示一个真正的单引号字符。format 的底层实现从 pkgs/core/src/format/index.ts 可以看到格式化字符串首先被拆解为两部分正则formattingTokensRegExp匹配yYQqMLwIdDecihHKkms等字母加o构成的序数令牌、连续的相同字母序列以及引号转义段longFormattingTokensRegExp则负责P/p开头的长格式令牌如PPPP。随后每个令牌交由_lib/format/formatters下的对应格式化器逐个渲染。对format的内部机制感兴趣的读者可以继续阅读 pkgs/core/src/_lib/format 目录。国际化I18n与按需引入 localedate-fns 内置数十种语言 locale。从 pkgs/core/package.json 的exports可以看到按语言代码划分的独立子路径导出如./locale/zh-CN、./locale/en-US、./locale/ja等每个 locale 均位于 pkgs/core/src/locale 目录。以简体中文为例import { format, formatDistance } from date-fns; import { zhCN } from date-fns/locale; format(new Date(2024, 0, 1), EEEE MMMM d, yyyy, { locale: zhCN }); // 输出中文星期与月份 formatDistance(subDays(new Date(), 3), new Date(), { locale: zhCN, addSuffix: true });每个 locale 都是一个符合统一Locale接口的对象。从 pkgs/core/src/locale/zh-CN/index.ts 的实现可以看到zhCN包含code、formatDistance、formatLong、formatRelative、localize、match六个成员并通过options.weekStartsOn: 1周一为一周起点与options.firstWeekContainsDate: 4声明该语言环境的周历规则。这些选项会直接影响依赖周历计算的函数如startOfWeek、getWeek、format中的w/E等令牌的结果。locale 的完整结构定义见 pkgs/core/src/locale/types.ts位于 pkgs/core/src/locale 目录内。由于每个 locale 都是独立子路径导出打包器可以轻松做 tree-shaking最终产物只包含实际用到的语言这也是“Include only what you need”理念的体现。进阶阅读更多函数与官方文档本文只覆盖了入门必需的部分。date-fns 的函数体系非常庞大按用途大致可分为几类运算类addDays、subMonths、addBusinessDays等加减操作比较类compareAsc、isAfter、isEqual、isSameDay等区间类eachDayOfInterval、areIntervalsOverlapping、intervalToDuration等取值/设值类getYear、setMonth、startOfWeek、endOfDay等解析类parse、parseISO、fromUnixTime等单位换算类hoursToMinutes、daysToWeeks、yearsToMonths等。所有这些函数都遵循同样的设计哲学纯函数、不修改入参、类型安全、按需导入。仓库内每个函数目录都包含index.ts实现与test.tsvitest 测试例如 pkgs/core/src/compareAsc 目录方便开发者阅读实现细节与行为契约。结语date-fns 用一套简单、一致、类型安全的函数把 JavaScript 日期操作的复杂度封装了起来安装只需一条 npm 命令使用遵循“按需导入 原生 Date 纯函数”的现代实践国际化与 FP 变体则让它能适配更多工程场景。希望本文能帮你快速建立起对 date-fns 的整体认知并在自己的项目中得心应手地使用它。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考