date-fns实现JS日期加减的代码示例

作者:木棉时间:2026-11-19 18:29:50浏览:181

使用轻量 JavaScript 日期库 date-fns 实现日、月、年及时间维度的加减计算,包含完整代码示例、不可变机制分析与月末边界处理要点。

在 JavaScript 中使用 date-fns 进行日期加减,核心做法是按需引入对应的加减函数(如 addDays、subMonths 等),传入基准日期和偏移数值,直接获取返回的全新日期对象。这种纯函数方式不修改原始日期,能自然规避原生 Date 就地修改和月末溢出的常见缺陷。

一、准备工作与安装配置

date-fns 是一个轻量级、模块化的 JavaScript 日期工具库,每个功能都拆分为独立函数,原生支持 Tree-shaking。在 Node.js 或现代前端工程中,可以通过包管理工具安装:

# 使用 npm 安装
npm install date-fns

# 或使用 pnpm 安装
pnpm add date-fns

在项目中可以按需引入加减函数,支持 ES Module(import)与 CommonJS(require)两种规范。为了控制前端最终打包体积,建议直接解构导入具体函数:

// ES Module 方式引入
import { addDays, subDays, addMonths, subMonths, add, sub } from 'date-fns';

// CommonJS 方式引入
// const { addDays, subDays, addMonths, subMonths, add, sub } = require('date-fns');
date-fns实现JS日期加减的代码示例
图 1:date-fns 日期加减的标准实现步骤

二、常用单一维度的加减代码示例

实际开发中,大部分日期计算只需要针对天数、月份或年份做单一维度的平移。date-fns 提供了命名直观的加减工具函数,统一遵循 fn(date, amount) 的参数签名。

1. 天数加减:addDays 与 subDays

处理“几天后到期”或“查询过去 N 天记录”时,可以使用 addDays 和 subDays。函数接受两个参数:第一个是基准 Date 对象,第二个是要偏移的整数天数。

import { addDays, subDays } from 'date-fns';

// 设定基准日期:2025年6月1日
const baseDate = new Date(2025, 5, 1); // 月份索引从 0 开始,5 代表 6月

// 加 7 天
const nextWeek = addDays(baseDate, 7);
console.log('加7天后:', nextWeek.toISOString().slice(0, 10));
// 示例输出:加7天后: 2025-06-08

// 减 3 天
const threeDaysAgo = subDays(baseDate, 3);
console.log('减3天后:', threeDaysAgo.toISOString().slice(0, 10));
// 示例输出:减3天后: 2025-05-29

// 验证原基准日期:原对象保持不变
console.log('原基准日期未改动:', baseDate.toISOString().slice(0, 10));
// 示例输出:原基准日期未改动: 2025-06-01

2. 月份与年份加减:addMonths、subMonths、addYears

处理按月续费、年度账单时,使用 addMonths 和 addYears。与天数加减类似,直接传入年份或月份数量即可完成换算。

import { addMonths, subMonths, addYears, subYears } from 'date-fns';

const currentDate = new Date(2025, 2, 15); // 2025-03-15

// 增加 2 个月
const afterTwoMonths = addMonths(currentDate, 2);
console.log('加2个月:', afterTwoMonths.toISOString().slice(0, 10));
// 示例输出:加2个月: 2025-05-15

// 减少 1 个月
const lastMonth = subMonths(currentDate, 1);
console.log('减1个月:', lastMonth.toISOString().slice(0, 10));
// 示例输出:减1个月: 2025-02-15

// 增加 1 年
const nextYear = addYears(currentDate, 1);
console.log('加1年:', nextYear.toISOString().slice(0, 10));
// 示例输出:加1年: 2026-03-15

3. 时间维度加减:小时、分钟与秒

针对时、分、秒级别的偏移,使用对应时间粒度的函数。例如倒计时计算、会话过期时间延长等场景:

import { addHours, subMinutes } from 'date-fns';

const eventTime = new Date('2025-08-10T14:00:00Z');

// 延后 3 小时
const laterTime = addHours(eventTime, 3);
console.log('延后3小时:', laterTime.toISOString());
// 示例输出:延后3小时: 2025-08-10T17:00:00.000Z

// 提前 45 分钟
const earlyTime = subMinutes(eventTime, 45);
console.log('提前45分钟:', earlyTime.toISOString());
// 示例输出:提前45分钟: 2025-08-10T13:15:00.000Z

三、关键机制差异:原生 JS 突变与 date-fns 不可变性

在理解 date-fns 的价值时,最关键的是对比它与原生 JavaScript Date 对象的修改行为。原生 Date 的计算方法(如 setDate、setMonth)采用的是就地突变(In-place Mutation),而 date-fns 坚持不可变纯函数(Immutability)。

在相同初始条件下,观察两者的行为差异:

// 场景对比:将当前日期向后推迟 5 天

// 1. 原生 JavaScript 原地修改
const nativeDate = new Date('2025-05-01');
const aliasRef = nativeDate; // 引用同一个内存地址
nativeDate.setDate(nativeDate.getDate() + 5);

console.log(nativeDate.toISOString().slice(0, 10)); // 2025-05-06
console.log(aliasRef.toISOString().slice(0, 10));   // 2025-05-06(别名变量被连带篡改)

// 2. date-fns 纯函数计算
import { addDays } from 'date-fns';
const fnsBaseDate = new Date('2025-05-01');
const fnsNextDate = addDays(fnsBaseDate, 5);

console.log(fnsBaseDate.toISOString().slice(0, 10)); // 2025-05-01(原对象保持原样)
console.log(fnsNextDate.toISOString().slice(0, 10)); // 2025-05-06(返回独立新实例)

这一差异之所以非常重要,是因为在现代前端框架(如 React、Vue)中,状态的可预测性直接决定了组件渲染的正确性。如果一个在父组件中维护的日期对象被子组件里的原生方法修改,会导致整个数据流出现隐蔽的污染,且难以定位原因。date-fns 保证传入的原始日期始终只读,每次运算都会在内存中实例化一个全新的 Date 返回,确保数据流的安全。

date-fns实现JS日期加减的代码示例
图 2:原生 Date 突变与 date-fns 纯函数内存机制对比

四、多维度复合计算:通用 add 与 sub 函数

当业务需要同时对多个不同粒度的时间进行偏移(例如“合同签署后 1 年 3 个月零 10 天后到期”,或者“扣除 2 小时 30 分钟缓冲期”)时,连续嵌套调用多个单一函数会显得代码层级较深。此时推荐使用通用的 add 和 sub 函数。

这两个函数接收一个 Duration 配置对象作为第二个参数,可在一次调用中声明多个维度的偏移量:

import { add, sub } from 'date-fns';

const startPoint = new Date(2025, 0, 10, 9, 0, 0); // 2025-01-10 09:00:00

// 同时增加:1年、2个月、15天、3小时
const complexFuture = add(startPoint, {
  years: 1,
  months: 2,
  days: 15,
  hours: 3,
});

console.log('复合增加后:', complexFuture.toLocaleString());
// 示例输出:复合增加后: 2026/3/25 12:00:00

// 同时减少:5天、30分钟
const complexPast = sub(startPoint, {
  days: 5,
  minutes: 30,
});

console.log('复合减少后:', complexPast.toLocaleString());
// 示例输出:复合减少后: 2025/1/5 08:30:00

下表归纳了 Duration 对象支持的配置属性及其含义:

属性名称 数据类型 含义说明
years number 偏移年份
months number 偏移月份
weeks number 偏移周数(1周 = 7天)
days number 偏移天数
hours number 偏移小时数
minutes number 偏移分钟数
seconds number 偏移秒数
date-fns实现JS日期加减的代码示例
图 3:date-fns 加减 API 矩阵与选型决策

五、月末与闰年边界处理规则

日期加减中最容易出现线上故障的环节是月末天数不一致。例如大月有 31 天,小月有 30 天,平年 2 月只有 28 天。原生 JavaScript 在处理“1 月 31 日加一个月”时,存在自动把超额天数溢出到 3 月的机制,这往往违背了业务常理。

// 原生 JavaScript 的溢出逻辑
const nativeJan = new Date(2025, 0, 31); // 2025-01-31
nativeJan.setMonth(nativeJan.getMonth() + 1); // 试图加 1 个月
console.log(nativeJan.toISOString().slice(0, 10));
// 示例输出:2025-03-03(2月没有31天,超出的3天溢出到3月,变成3月3日)

// date-fns 的智能截断逻辑
import { addMonths } from 'date-fns';
const fnsJan = new Date(2025, 0, 31); // 2025-01-31
const fnsFeb = addMonths(fnsJan, 1);
console.log(fnsFeb.toISOString().slice(0, 10));
// 示例输出:2025-02-28(平年自动校准至2月最后一天)

// 遇到闰年时:
const leapJan = new Date(2024, 0, 31); // 2024年为闰年
const leapFeb = addMonths(leapJan, 1);
console.log(leapFeb.toISOString().slice(0, 10));
// 示例输出:2024-02-29(闰年自动校准至2月29日)

date-fns 内部通过比对目标月份的实际最大天数,在目标月份天数不足时,自动将日期对齐到目标月份的最后一天,而不会跨月跳跃。这种机制完全符合人类在处理账期、会员订阅周期的真实预期。

date-fns实现JS日期加减的代码示例
图 4:月末边界自适应对齐与计算校验机制

六、实践注意事项与常见问题排查

在生产环境中运用 date-fns 执行日期加减时,建议关注以下细节,以保证系统长期稳定运行:

  1. 输入参数类型校验: date-fns 的加减函数要求第一个参数为合法的 Date 实例或时间戳数字。如果业务数据是字符串格式(如 "2025-05-01"),直接传入可能因运行环境的时区差异产生偏差。建议先使用 parseISO 解析成合法日期实例后再执行加减。
  2. 正负偏移量的语义选择: 虽然 addDays(date, -3) 与 subDays(date, 3) 计算结果一致,但在团队协作中,优先使用明确反映业务动作的函数(向前推算用 subDays,向后推算用 addDays),代码的自解释性更好。
  3. 夏令时(DST)跨越影响: 如果系统服务跨越夏令时切换区域,addDays 保持的是“历法上的同一时刻”(即加 1 天后依然是次日的上午 10 点),而不会简单粗暴地增加绝对的 86400000 毫秒。这在涉外业务中尤为重要。
  4. 与格式化函数搭配使用: 加减运算输出的依旧是原生 Date 对象,如果需要给前端展示或回传给后端,可以无缝搭配 date-fns 的 format 函数(例如 format(resultDate, 'yyyy-MM-dd HH:mm:ss'))输出标准文本。
作者最新文章
相关文章
更多