详细讲解在 dayjs 与 date-fns 中获取当前年份的完整代码示例,涵盖数值类型与字符串格式化提取方法、设计架构差异、YYYY 与 yyyy 的跨年占位符陷阱排查及工程选型建议。
dayjs 和 date-fns 中获取当前年份的代码示例
时间:2026-11-17
浏览:474
文章目录
dayjs().year() 获取数字类型年份,或使用 dayjs().format('YYYY') 获取格式化字符串;而在 date-fns 中,则通过纯函数 getYear(new Date()) 提取数字年份,或调用 format(new Date(), 'yyyy') 得到字符串年份。下文将完整展示两者的代码示例、工程配置、架构差异及不可忽视的跨年占位符陷阱。
一、核心结论与快速代码对照
获取年份的需求通常细分为两类:一类用于年龄计算、跨度统计等业务逻辑运算,需要 number 数值类型;另一类用于页面版权宣告(如 © 2026)、表单回显或报表导出,需要 string 字符串类型。
以下是两个库在处理这两种场景时最直接的代码对照:
// 1. dayjs 方案
import dayjs from 'dayjs';
const currentYearNum = dayjs().year(); // 2026 (数值类型)
const currentYearStr = dayjs().format('YYYY'); // "2026" (字符串类型)
// 2. date-fns 方案
import { getYear, format } from 'date-fns';
const dateFnsYearNum = getYear(new Date()); // 2026 (数值类型)
const dateFnsYearStr = format(new Date(), 'yyyy'); // "2026" (字符串类型,注意小写 yyyy)
二、在 dayjs 中获取当前年份的具体实践
dayjs 是一个极轻量级的日期时间库,设计上深度兼容 Moment.js 的链式语法体系,其核心代码打包体积仅约 2KB。在 dayjs 的模型中,调用 dayjs() 时若不传任何参数,默认会以当前的本地客户端时间创建一个不可变的 Dayjs 包装对象。
1. 安装与模块导入
在项目中通过包管理器安装 dayjs:
npm install dayjs
# 或者使用 pnpm / yarn
pnpm add dayjs
在业务代码中根据工程环境选择导入方式:
// ES 模块规范 (ESM / Vite / Webpack / Next.js)
import dayjs from 'dayjs';
// CommonJS 规范 (Node.js 传统环境)
const dayjs = require('dayjs');
2. 获取数字型年份:dayjs().year()
.year() 方法是 Dayjs 实例上的原生 Getter/Setter 方法。当不传实参时,它执行 Getter 行为,返回一个 4 位数的整数:
// 获取当前时间的年份整数
const year = dayjs().year();
console.log(year); // 输出示例:2026
console.log(typeof year); // 输出:"number"
// 等价用法:使用通用 get 方法
const sameYear = dayjs().get('year'); // 2026
在实现上,dayjs().year() 本质上调用了包装在内部的原生 Date.prototype.getFullYear(),因此其返回值与运行环境的本地时区保持完全一致。
3. 获取字符串格式化年份:dayjs().format('YYYY')
当需要在界面上展示文本或拼接日历前缀时,推荐使用 .format() 函数:
// 仅提取 4 位年份字符串
const yearString = dayjs().format('YYYY');
console.log(yearString); // 输出示例:"2026"
console.log(typeof yearString); // 输出:"string"
// 提取 2 位简短年份(例如 26)
const shortYear = dayjs().format('YY');
console.log(shortYear); // 输出示例:"26"
// 在页面页脚版权中动态渲染
const copyrightText = `Copyright © ${dayjs().format('YYYY')} Inc.`;
console.log(copyrightText); // 输出:"Copyright © 2026 Inc."
三、在 date-fns 中获取当前年份的具体实践
与 dayjs 不同,date-fns 并不提供全局的大对象包装,而是将各个日期操作设计为一组功能单一、互相独立的纯函数。它直接操作 JavaScript 原生 Date 实例,因而在现代支持 Tree-shaking 的构建工具中能够实现极高的打包精简度。
1. 安装与按需导入
安装 date-fns(推荐使用 v3 及以上版本):
npm install date-fns
# 或者使用 pnpm / yarn
pnpm add date-fns
通过解构语法按需引入所需函数,打包工具会自动剔除未被引用的数百个其他日期函数:
// 推荐用法:按需引入核心函数
import { getYear, format } from 'date-fns';
// 针对不支持命名导出的旧环境,可直接从子路径导入
// import getYear from 'date-fns/getYear';
2. 获取数字型年份:getYear(new Date())
getYear 函数接收一个日期对象并返回对应的年份数字。注意,date-fns 不会自动生成当前时间,必须显式传入 new Date():
// 显式传入当前原生 Date 对象
const now = new Date();
const currentYear = getYear(now);
console.log(currentYear); // 输出示例:2026
console.log(typeof currentYear); // 输出:"number"
3. 获取字符串格式化年份:format(new Date(), 'yyyy')
使用 date-fns 的 format 函数可以将当前时间格式化为指定文本结构:
const now = new Date();
// 获取 4 位日历年份字符串(注意:必须是全小写 yyyy)
const formattedYear = format(now, 'yyyy');
console.log(formattedYear); // 输出示例:"2026"
console.log(typeof formattedYear); // 输出:"string"
// 获取 2 位简短年份(小写 yy)
const shortYear = format(now, 'yy');
console.log(shortYear); // 输出示例:"26"
四、关键陷阱:格式化占位符 YYYY 与 yyyy 的致命差异
在日常业务开发中,开发者在从 dayjs 切换到 date-fns(或者混合使用两者)时,最常踩到的暗坑就是占位符的大小写定义。如果在 date-fns 中习惯性地使用大写 YYYY,会在每年 12 月底或 1 月初引发极其隐蔽的线上故障。
date-fns 中,小写 yyyy 代表常规日历年(Calendar Year),而大写 YYYY 代表 ISO 周纪年份(Week-numbering year)。若在 2025 年 12 月 31 日调用 format(new Date(2025, 11, 31), 'YYYY'),计算出的年份将是 "2026",导致提早整整一年!
造成这种差异的根本原因在于两个库所遵循的规范体系不同:
-
dayjs 采用 Moment 占位符规范:规定
YYYY表示 4 位公历年(Calendar Year),这是绝大多数开发者最熟悉的直觉写法。在 dayjs 中,若误写为小写yyyy,由于它不识别该 token,会直接原样输出字符"yyyy"。 -
date-fns 严格遵循 Unicode 技术标准(LDML):标准规定小写
y/yyyy才是普通日历年份;大写Y/YYYY被专门保留给基于 ISO 8601 周数的年份计算。在 ISO 规则中,一年的第一周是包含该年 4 天及以上的新周。如果 12 月最后几天恰好与新年的第一周重叠,该周将被视为新年的第 1 周,其YYYY将直接跃迁至下一年。
以下代码清楚地展示了这种异常表现:
import { format } from 'date-fns';
// 构造一个处于跨年交叉周的日期:2025年12月30日(周二)
const crossYearDate = new Date(2025, 11, 30);
// 正确写法:使用小写 yyyy
console.log(format(crossYearDate, 'yyyy-MM-dd')); // "2025-12-30" (符合业务预期)
// 错误写法:误用大写 YYYY
console.log(format(crossYearDate, 'YYYY-MM-dd')); // "2026-12-30" (严重故障:年份超前)
五、综合对比与工程选型建议
为了方便在实际项目中根据架构需求进行技术决策,下面整理了两个库在获取当前年份及相关日常操作中的横向比对:
| 对比项 | dayjs | date-fns |
|---|---|---|
| 核心设计哲学 | 面向对象链式封装,API 高度对齐 Moment.js | 函数式编程,零封装开销,直接操作原生 Date |
| 获取年份数字 | dayjs().year() |
getYear(new Date()) |
| 格式化年份文本 | dayjs().format('YYYY')(大写) |
format(new Date(), 'yyyy')(小写) |
| 当前时间缺省能力 | 内置。dayjs() 默认生成当前时间 |
无内置状态。必须显式传入 new Date() |
| 打包体积表现 | 固定核心体积约 2KB(Gzip) | 完全支持 Tree-shaking,按需引入几十字节 |
| TypeScript 支持 | 提供完整类型声明文件,易用度高 | 原生强类型,严格校验原生 Date 与参数合法性 |
选型建议:
-
选择 dayjs 的场景:如果你的团队正在将旧的 Moment.js 项目进行瘦身迁移,或者业务中需要频繁进行诸如
dayjs().startOf('year').add(1, 'month').format(...)这类多步链式计算,dayjs 能够提供最顺畅、符合直觉的书写体验。 - 选择 date-fns 的场景:如果你的项目属于对首屏资源体积控制极其严苛的前端应用、微前端子模块,或者整体代码架构基于纯函数风格构建,date-fns 能够最大化利用打包工具的摇树优化能力,避免引入任何多余代码。
六、常见问题与边界细节
1. 为什么不直接使用原生 JavaScript 的 getFullYear()?
原生 JavaScript 提供了 new Date().getFullYear(),如果你的项目中仅仅只有获取当前年份一个需求,完全不需要安装任何第三方日期库,直接使用原生 API 是性能最好、体积为零的最佳方案。
之所以引入 dayjs 或 date-fns,是因为实际项目中通常伴随着更复杂的日期解析、多语言本地化、时区切换、跨月计算和统一格式化需求。在已有库的工程中,保持统一的日期处理调用方式能够提升团队代码的一致性。
2. 时区差异对“当前年份”判定的影响
无论是 dayjs() 还是 new Date(),默认获取的都是执行代码机器上的本地操作系统时间。在跨年那一刻(例如 12 月 31 日 23:59:59),北京时间(UTC+8)已经进入新年,而伦敦时间(UTC+0)依然属于上一年。
如果服务端日志或跨国业务要求统一按 UTC 判定年份,两个库的处理方式如下:
// dayjs: 需引入 utc 插件
import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
dayjs.extend(utc);
const utcYear = dayjs.utc().year();
// 原生 Date 与 date-fns: 原生自带 getUTCFullYear
const nativeUtcYear = new Date().getUTCFullYear();
dayjs().year(),建议通过依赖注入传入时间基准,或使用类似 Jest 提供的 jest.useFakeTimers().setSystemTime(...) 固定时间点,防止测试用例在跨年夜出现意外失败。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。