用dayjs简化JS时间差计算:diff方法使用教程

作者:代码拾荒

时间:2026-11-21

浏览:166

详细讲解如何使用 Day.js 的 diff 方法计算两个时间点之间的差距。涵盖核心语法、常见时间单位、浮点数精度控制、时间差方向规则及常见避坑要点,提供完整可执行代码示例。

文章目录
实用技术教程
用dayjs简化JS时间差计算:diff方法使用教程
图 0:Day.js diff() 方法核心特性与使用概览
在 JavaScript 前端与服务端开发中,计算两个时间点相差几天、几月或几小时是常见需求。直接使用原生 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 方法则将这些底层日历感知规则封装在内,对外提供语义统一的接口。

用dayjs简化JS时间差计算:diff方法使用教程
图 1:原生 Date 与 Day.js 时间差计算逻辑对比

二、基础环境准备与引入

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
用dayjs简化JS时间差计算:diff方法使用教程
图 2:diff 计算方向原理与内部三步执行流

四、支持的时间单位与实际业务场景

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"
用dayjs简化JS时间差计算:diff方法使用教程
图 3:diff 取整截断与浮点精度对照示意

六、日常开发中的四个常见避坑点

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 方法,记住以下四条黄金法则即可应对大多数日常开发场景:

  1. 看清减法方向:A.diff(B) 是 A - B,晚减早为正,早减晚为负。
  2. 明确单位全拼:不传参数默认是毫秒;缩写中 M 为月,m 为分。
  3. 掌握截断规则:默认向 0 截断小数,不四舍五入;需要精确小数时传入第三个参数 true。
  4. 灵活传入参数:参数支持字符串、时间戳与 Date 实例,无需手动多层转换。
用dayjs简化JS时间差计算:diff方法使用教程
图 4:Day.js diff 方法核心要点与速查全景图

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章