详细讲解如何使用 Day.js 的 diff 方法计算两个时间点之间的差距。涵盖核心语法、常见时间单位、浮点数精度控制、时间差方向规则及常见避坑要点,提供完整可执行代码示例。
用dayjs简化JS时间差计算:diff方法使用教程
时间:2026-11-21
浏览:166
文章目录
Date 对象进行毫秒数换算往往容易忽略月份天数不同、闰年及夏令时等问题。体积仅约 2KB 的 Day.js 提供了专门的 diff 方法,只需传入目标时间与度量单位,即可通过一行声明式代码准确得出时间差。本文详细讲解 diff 方法的传参规则、时间减法方向、单位换算机制、浮点数精度控制以及日常开发中的避坑要点。
一、原生 Date 的局限与 Day.js 的简化方案
在没有时间处理库的辅助下,使用原生 JavaScript 计算两个日期的差距通常依赖时间戳:
// 原生 JavaScript 手动计算相差天数示例
const d1 = new Date('2026-03-01');
const d2 = new Date('2026-03-16');
const diffMs = d2.getTime() - d1.getTime();
const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
console.log(diffDays); // 示例输出: 15
这种手动除以固定进率的方法在计算“天”、“小时”或“分钟”时看似简单,但在面对真实业务场景时存在明显缺陷:
- 月份长度不固定:自然月有 28、29、30、31 天之分。直接通过
diffMs / (30 * 86400000)估算月份差值,会随着跨度增大产生不可忽视的累积误差。 - 夏令时跳变隐患:在涉及跨时区或支持夏令时(DST)的地区,一天的实际物理时长可能是 23 小时或 25 小时,直接按 24 小时整除容易导致计算出的天数产生 ±1 天的偏差。
- 负数向下取整陷阱:
Math.floor(-1.2)会返回-2,导致负数差值与正数差值的取整行为不对称。
Day.js 的 diff 方法则将这些底层日历感知规则封装在内,对外提供语义统一的接口。
二、基础环境准备与引入
Day.js 是一个零依赖的轻量级日期库,diff 方法内置于核心包中,无需额外引入外部插件即可直接使用。
1. 项目中通过包管理器安装
# 使用 npm 安装
npm install dayjs
# 或使用 pnpm / yarn
pnpm add dayjs
yarn add dayjs
2. 在代码中导入
// ES Module 引入方式
import dayjs from 'dayjs';
// CommonJS 引入方式
const dayjs = require('dayjs');
如果在浏览器无构建环境下使用,也可直接通过 script 标签引入 CDN 地址,引入后全局变量 window.dayjs 便可直接调用。
三、diff 方法核心语法与方向规则
diff 方法的基本调用形式如下:
dayjsObj.diff(comparedDate, unit, float);
1. 核心计算方向:被调用方减去传入方
理解 diff 方法的关键在于记住减法方向:调用方(前面的对象)减去参数方(括号里的对象)。即:
dateA.diff(dateB) 等价于数学上的 dateA - dateB。
- 如果
dateA比dateB晚(未来),差值为正数。 - 如果
dateA比dateB早(过去),差值为负数。 - 如果两个时间点完全相同,差值为 0。
const d1 = dayjs('2026-05-01');
const d2 = dayjs('2026-05-10');
// d2 晚于 d1,结果为正数
console.log(d2.diff(d1, 'day')); // 示例输出: 9
// d1 早于 d2,结果为负数
console.log(d1.diff(d2, 'day')); // 示例输出: -9
四、支持的时间单位与实际业务场景
diff 方法的第二个参数用于指定返回值的度量单位。Day.js 支持完整英文单词或缩写形式:
| 度量单位 | 全称参数(大小写均可) | 缩写参数(注意大小写) | 说明与计算依据 |
|---|---|---|---|
| 年 | 'year' |
'y' |
按自然公历年计算整年跨度 |
| 月 | 'month' |
'M'(大写) |
按自然公历月份换算,充分考虑月份长短 |
| 周 | 'week' |
'w' |
以 7 天为一个计算周期 |
| 天 | 'day' |
'd' |
以 24 小时为一个计算周期 |
| 小时 | 'hour' |
'h' |
物理小时差值 |
| 分钟 | 'minute' |
'm'(小写) |
注意与月份大写 'M' 区分 |
| 秒 | 'second' |
's' |
秒数差值 |
| 毫秒 | 'millisecond' |
'ms' |
默认单位,未指定 unit 时生效 |
'M' 表示月份(Month),而 'm' 表示分钟(minute)。建议初学者优先书写全称 'month' 与 'minute' 以免混淆。
常见业务场景示例
场景一:合同到期日或剩余倒计时天数
const today = dayjs('2026-04-10');
const expireDate = dayjs('2026-04-25');
// 计算到期剩余天数
const remainingDays = expireDate.diff(today, 'day');
console.log(`距离服务到期还剩 ${remainingDays} 天`); // 示例输出: 距离服务到期还剩 15 天
场景二:工龄或年龄跨度计算
const hireDate = dayjs('2023-03-15');
const currentDate = dayjs('2026-06-20');
// 计算工龄整年数与整月数
const years = currentDate.diff(hireDate, 'year');
const months = currentDate.diff(hireDate, 'month');
console.log(`在职满 ${years} 年,折合共 ${months} 个月`); // 示例输出: 在职满 3 年,折合共 39 个月
场景三:接口请求与任务执行耗时统计
const startTime = dayjs();
// 执行异步任务...
const endTime = dayjs();
// 获取耗时(毫秒)
const durationMs = endTime.diff(startTime); // 省略单位默认为毫秒
console.log(`任务耗时: ${durationMs}ms`);
五、浮点数与截断机制(第三个参数 float)
默认情况下,diff 返回的是经过截断后的整数。如果需要精确到小数,需要理解其第三个布尔参数 float。
1. 默认模式:向零截断(Truncate Toward Zero)
当第三个参数为 false 或未传递时,Day.js 会将计算出的结果直接去除小数部分。
需要明确的是,这种截断不是四舍五入,也与 Math.floor() 不同:
- 如果间隔是
1.9天,结果会被截断为1(不会四舍五入进位为 2)。 - 如果间隔是
-1.9天,向零截断后结果为-1(而Math.floor(-1.9)会得出 -2)。
2. 开启高精度浮点模式:传入 true
将第三个参数显式设置为 true,diff 将返回完整的双精度浮点数,便于后续进行精确展示或二次计算。
const start = dayjs('2026-01-01 12:00:00');
const end = dayjs('2026-01-02 18:00:00');
// 默认模式:30 小时折合 1.25 天,向零截断后得 1
console.log(end.diff(start, 'day')); // 示例输出: 1
// 开启浮点模式:返回完整的 1.25
console.log(end.diff(start, 'day', true)); // 示例输出: 1.25
// 配合 toFixed 保留指定小数位数
const accurateDays = end.diff(start, 'day', true).toFixed(1);
console.log(accurateDays); // 示例输出: "1.3"
六、日常开发中的四个常见避坑点
1. 省略度量单位时的默认值是毫秒
许多初次使用 Day.js 的开发者会误以为省略参数时默认按“天”计算。实际上,date1.diff(date2) 返回的是毫秒数差值。若要计算天数,必须显式传递 'day'。
2. 参数类型的多态支持
diff 括号内的第一个参数不仅支持另一个 Dayjs 对象,还可以直接传入原生 Date 实例、符合标准的日期字符串或 Unix 时间戳。Day.js 内部会自动将其转换为 Dayjs 实例,无需每次都手动包装:
const d = dayjs('2026-06-01');
// 以下四种传参方式均合法且等效
d.diff(dayjs('2026-05-01'), 'day');
d.diff(new Date('2026-05-01'), 'day');
d.diff('2026-05-01', 'day');
d.diff(1777593600000, 'day');
3. 自然月份边界的处理
当计算两个日期相差几个月时,Day.js 会比对日期(Date of Month)。如果起始日期是 1 月 31 日,目标日期是 2 月 28 日,尽管 2 月没有 31 号,但在日历认知上它已到达 2 月的月末,dayjs('2026-02-28').diff('2026-01-31', 'month') 结果为 0(因物理上未满一个月)。而如果目标是 2 月最后一天且跨月度量要求按账期计算,业务层需根据实际规则判断是否传入 float=true 或结合月份做补充判定。
4. 跨时区场景保持一致
默认情况下,Day.js 读取的是客户端浏览器的本地时区。若比对的两个时间字符串带有不同时区偏移(例如一个带 +08:00,另一个为 UTC 的 Z),Day.js 会先将其换算为同一基准时间点再算差值。如果需要统一切换为标准 UTC 时间运算,建议搭配官方的 utc 插件。
七、核心要点速查与总结
掌握 Day.js 的 diff 方法,记住以下四条黄金法则即可应对大多数日常开发场景:
- 看清减法方向:
A.diff(B)是A - B,晚减早为正,早减晚为负。 - 明确单位全拼:不传参数默认是毫秒;缩写中
M为月,m为分。 - 掌握截断规则:默认向 0 截断小数,不四舍五入;需要精确小数时传入第三个参数
true。 - 灵活传入参数:参数支持字符串、时间戳与 Date 实例,无需手动多层转换。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。