深入详解 JavaScript Date 对象的核心 API,系统讲解获取与设置年月日时分秒的常用方法、取值范围、月份偏移校准、补零技巧与自动滚转机制。
JS Date对象常用API详解:获取与设置年月日时分秒
时间:2026-11-16
浏览:123
文章目录
Date 实例的年、月、日、时、分、秒六大维度展开。JavaScript 标准库提供了一组高度对称的 Getter 和 Setter 方法。理解其基于 Unix 纪元时间戳的底层结构、掌握以 0 为起点的月份索引规则以及 Setter 的自动进位特性,是编写精准、健壮时间处理代码的核心关键。
一、Date 实例创建与底层时间模型
在调用具体的读取与修改方法之前,必须明确 Date 对象的存储本质。在 JavaScript 引擎底层,每个 Date 实例内部仅保存着一个 64 位浮点整数。该数值代表自 1970 年 1 月 1 日 00:00:00 UTC(即 Unix 时间纪元)起流逝的毫秒数。
我们平常调用的 getFullYear() 或 getHours(),本质上都是宿主环境(浏览器或 Node.js 运行时)根据操作系统当前配置的本地时区(Local Timezone),实时将该毫秒数值转换为对应日历分量的结果。
// 1. 创建代表当前时刻的 Date 实例
const now = new Date();
// 2. 基于毫秒时间戳创建
const fromTimestamp = new Date(1773705600000);
// 3. 基于具体的年月日时分秒数值创建(注意:月份从 0 开始算)
// 下例表示 2026 年 5 月 15 日 14:30:00
const customDate = new Date(2026, 4, 15, 14, 30, 0);
二、获取年月日时分秒:核心 Getter API
获取本地时间分量需使用以 get 开头的方法。以下是日常开发中最常用的六个方法及其详细行为说明:
-
年份
getFullYear():返回四位的公历完整年份(例如2026)。注意:早期的getYear()方法返回的是当前年份减去 1900(如 2026 年会返回 126),属于已废弃的历史遗留接口,现代开发中必须严格使用getFullYear()。 -
月份
getMonth():返回当前日期的月份索引,取值范围是 0 到 11(0代表 1 月,11代表 12 月)。在对外展示或拼接人类可读字符串时,必须显式进行+ 1换算。 -
日期
getDate():返回当前月份中的具体天数(即几号),取值范围为 1 到 31。务必注意不要将其与getDay()混淆,后者返回的是星期几(0 代表周日,1 到 6 代表周一至周六)。 -
小时
getHours():返回当前时刻的小时数,采用 24 小时制,取值范围为 0 到 23。 -
分钟
getMinutes():返回当前时刻的分钟数,取值范围为 0 到 59。 -
秒数
getSeconds():返回当前时刻的秒数,取值范围为 0 到 59。
此外,若需更精细的控制,还可以使用 getMilliseconds() 获取毫秒数(0 ~ 999),或通过 getTime() 直接读取底层毫秒时间戳。以下为完整提取各分量的基础代码:
const target = new Date();
const year = target.getFullYear(); // 完整年份,如 2026
const month = target.getMonth() + 1; // 需手动 +1 还原真实月份 (1~12)
const date = target.getDate(); // 当月几号 (1~31)
const hours = target.getHours(); // 小时 (0~23)
const minutes = target.getMinutes(); // 分钟 (0~59)
const seconds = target.getSeconds(); // 秒数 (0~59)
console.log(`当前读取分量: ${year}年${month}月${date}日 ${hours}:${minutes}:${seconds}`);
三、设置与修改时间分量:核心 Setter API
修改现有 Date 实例的时间分量,使用对应的 set 系列方法。每个 Setter 接收整数作为参数,并直接更新底层时间戳。
-
设置年份
setFullYear(yearValue [, monthValue [, dateValue]]):必填四位年份整数。可选级联传入月份(0~11)和日期(1~31)。 -
设置月份
setMonth(monthValue [, dateValue]]):传入 0 到 11 的月份数值。例如要设置为 8 月,应传入7。 -
设置日期
setDate(dayValue):传入 1 到 31 的天数值。 -
设置小时
setHours(hoursValue [, minVal [, secVal [, msVal]]]):传入 0 到 23 的小时数值,同时可级联重置分、秒和毫秒。 -
设置分钟
setMinutes(minVal [, secVal [, msVal]]):传入 0 到 59 的分钟数值。 -
设置秒数
setSeconds(secVal [, msVal]):传入 0 到 59 的秒数值。
当向 Setter 传入超出正常区间的值时(例如 setDate(35) 或 setMinutes(75)),JavaScript 引擎不会抛出异常,而是根据超出的数值自动向前或向后滚转。例如:在 3 月 1 日执行 d.setDate(0),会将日期自动回退至 2 月的最后一天;在 10:15 执行 d.setMinutes(75),会自动变为 11:15。该特性广泛应用于时间加减法运算。
const d = new Date(2026, 2, 10, 8, 0, 0); // 2026-03-10 08:00:00
// 1. 设置具体年份与月份
d.setFullYear(2028);
d.setMonth(5); // 调整为 6 月
// 2. 利用自动进位进行“加 25 天”运算
d.setDate(d.getDate() + 25);
// 3. 将时分秒统一归零(常见于获取当天零点)
d.setHours(0, 0, 0, 0);
console.log(d.toISOString());
四、常见陷阱与避坑指南
在实际项目中使用原生 Date API 时,以下几个细节最容易引发隐蔽的业务 Bug,需要格外警惕:
1. 陷阱一:月份是基于 0 的索引
人类日常直觉中的 1 月到 12 月,在 Date 对象中被表示为索引 0 到 11。忘记 + 1 会导致显示的所有月份偏小 1 个月;而在调用 setMonth 时若直接传入人类月份,则会导致月份自动跳后 1 个月。
2. 陷阱二:getDate() 与 getDay() 混淆
许多初学者会习惯性认为 getDay() 获取的是“日(几号)”。实际上,getDate() 才是当前月份的具体号数(1~31),而 getDay() 返回的是星期几(0 为周日,1~6 为周一至周六)。混淆这两个方法会在日期校验与表单渲染中引发严重逻辑错误。
3. 陷阱三:原生 Setter 会原地修改实例(In-Place Mutation)
所有的 setXxx 方法都会直接改变原 Date 对象的内部状态,而不是返回一个新的实例。如果该对象是从函数参数传入或作为组件状态共享,直接调用 Setter 将引发严重的非预期副作用。因此,在做时间推算前,应先通过 new Date(origin.getTime()) 克隆一份独立副本。
4. 陷阱四:短日期字符串解析的时区偏差
根据 ECMAScript 标准,执行 new Date("2026-05-01") 时,ISO 8601 格式的纯日期字符串会被当做 UTC 时间零点 解析;在中国标准时间(UTC+8)环境下读取时,getDate() 可能会因为时差退回前一天的 8 点(即输出为 4 月 30 日)。为了避免时区漂移,建议优先使用数值传参 new Date(2026, 4, 1) 或规范的带时区格式。
五、实战场景:规范时间格式化与日期运算
基于上述 API,我们可以封装日常业务中最常用的通用格式化函数和安全时间计算函数。
场景 1:无依赖的高性能时间格式化
格式化时,使用 ES2017 引入的 String.prototype.padStart(2, '0') 方法,可以极其优雅地完成单数日期的前置补零:
/**
* 将 Date 实例格式化为 YYYY-MM-DD HH:mm:ss 格式
* @param {Date} [date=new Date()] 目标时间实例
* @returns {string} 格式化结果
*/
function formatDateTime(date = new Date()) {
const pad = (n) => String(n).padStart(2, '0');
const year = date.getFullYear();
const month = pad(date.getMonth() + 1);
const day = pad(date.getDate());
const hours = pad(date.getHours());
const minutes = pad(date.getMinutes());
const seconds = pad(date.getSeconds());
return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
}
console.log(formatDateTime(new Date())); // 示例输出:"2026-05-15 09:05:08"
场景 2:安全计算当月总天数
利用 new Date(year, monthIndex, 0) 的滚转机制,将“第 0 天”传入目标月份后一个月的构造函数中,即可自动回滚到目标月份的最后一天,从而直接获取当月真实天数(无需繁琐判断闰年):
/**
* 获取指定年月的实际总天数
* @param {number} year 目标年份(如 2026)
* @param {number} month 实际月份(1 ~ 12)
* @returns {number} 当月天数(28/29/30/31)
*/
function getDaysInMonth(year, month) {
// 传入 month 作为索引(即真实月份的下一个月),日期传 0 则自动获取该月倒数第 0 天(即上一月最后一天)
return new Date(year, month, 0).getDate();
}
console.log(getDaysInMonth(2026, 2)); // 示例输出:28(平年 2 月)
console.log(getDaysInMonth(2028, 2)); // 示例输出:29(闰年 2 月)
六、API 对称速查矩阵与小结
为了便于日常开发随时查阅,下表系统总结了 JavaScript 原生操作年月日时分秒的完整 API 对称关系:
| 时间分量 | Getter 方法 | Setter 方法 | 合法取值范围 | 核心开发提示 |
|---|---|---|---|---|
| 年份 (Year) | getFullYear() |
setFullYear() |
4位完整整数 | 严禁使用已废弃的 getYear() |
| 月份 (Month) | getMonth() |
setMonth() |
0 ~ 11 | 以 0 为基数;读取需 +1,设置需 -1 |
| 日期 (Date) | getDate() |
setDate() |
1 ~ 31 | 代表月份中几号;切勿与代表星期的 getDay() 混淆 |
| 小时 (Hours) | getHours() |
setHours() |
0 ~ 23 | 采用 24 小时制;数值超限自动向天数进位 |
| 分钟 (Minutes) | getMinutes() |
setMinutes() |
0 ~ 59 | 数值超限自动向小时进位或退位 |
| 秒数 (Seconds) | getSeconds() |
setSeconds() |
0 ~ 59 | 数值超限自动向分钟进位或退位 |
熟练掌握原生 Date 对象这六组基础 API,不仅能够使我们轻松脱离沉重的外部第三方时间库实现高精度的轻量格式化与计算,更能让我们深刻理解底层时间戳与本地时间映射的运作机制。在面对诸如月份 0 索引、原地突变、超界滚转等特性时做到心中有数,写出更加稳定、健壮的前后端代码。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。