JavaScript Date对象常用方法速查与实例化详解

作者:拾光时间:2026-11-22 14:12:59浏览:179

系统讲解JavaScript Date对象的5种实例化方式、字符串解析时区差异、常用读取/修改/格式化方法速查,以及日期加减与避坑实践。

JavaScript Date对象常用方法速查与实例化详解
JavaScript Date 对象核心结构:多种输入构造为单一 UTC 时间戳,再通过读取、修改与格式化方法对外输出。

写前端或 Node.js 代码时,很多人第一次踩 Date 的坑,往往是因为传入 new Date('2026-05-12') 后,在东八区环境里取出的小时数变成了 8;紧接着又会发现 getMonth() 对 5 月返回了 4。其实只要搞清楚 Date 内部只存一个 UTC 毫秒时间戳,并分清五种实例化方式和四类方法的作用边界,这些问题都能一次性理顺。本文会先讲透 Date 的内部模型与实例化细节,再提供按用途归类的常用方法速查表和常见操作写法。

一、理解 Date 的底层模型:一个时间戳与两套视角

在 JavaScript 中,无论通过哪种方式创建 Date 实例,对象内部保存的既不是“年月日字符串”,也不是时区信息,而仅仅是一个以 UTC 1970 年 1 月 1 日 00:00:00.000 为起点的毫秒整数(有效范围是起点前后各 8.64e15 毫秒,约正负 27 万年)。

之所以同一个 Date 对象在不同方法下表现出不同的时间,是因为它提供了两套读取与修改视角:

  • 本地时间视角(默认):如 getHours()、toString()、toLocaleString(),会读取运行环境当前系统的时区偏移,把内部 UTC 时间戳换算成本地时间。
  • UTC 视角:如 getUTCHours()、toISOString(),直接按零时区(UTC)拆解,不受设备所在时区影响。
JavaScript Date对象常用方法速查与实例化详解
图 1:Date 实例内部仅维护一个 UTC 毫秒值,创建时可能发生时区换算,读取时则取决于调用本地方法还是 UTC 方法。

二、Date 实例化的五种方式与解析细节

创建 Date 对象必须使用 new Date(...)。如果不写 new 直接调用 Date(),无论传什么参数,都会忽略参数并返回一个代表当前时间的字符串,而不是 Date 实例,因此无法调用 getFullYear() 等实例方法。

1. 无参数:获取当前时刻

new Date() 会根据当前系统时钟创建一个代表此时此刻的实例。

const now = new Date();
console.log(now instanceof Date); // 示例判断: true
console.log(typeof Date());       // 示例判断: "string"(未加 new)

2. 传入数字:毫秒时间戳

new Date(timestamp) 接收一个数字作为毫秒时间戳。后端接口(尤其是 Python、PHP、Go 或 MySQL Unix 时间戳)常返回 10 位的秒级时间戳,而 JavaScript 需要 13 位的毫秒级时间戳。直接把 10 位数传给 new Date() 会得到 1970 年 1 月的某一天,务必先乘以 1000。

const fromMs = new Date(1778544000000);       // 2026-05-12T00:00:00.000Z
const fromSec = new Date(1778544000 * 1000);  // 秒级时间戳先乘以 1000

3. 传入字符串:ISO 8601 与时区陷阱

这是最容易产生 8 小时偏差的实例化方式。按照 ECMAScript 规范,new Date(dateString)(内部规则与 Date.parse() 一致)对 ISO 8601 格式字符串的处理有明确区分:

  • 纯日期字符串(不含时间):如 '2026-05-12'、'2026-05',规范强制按 UTC 零点解析。在东八区调用 getHours() 会得到 8;如果写成 '2026-05-12' 想表示本地零点,结果就会偏移。
  • 带时间但无时区后缀:如 '2026-05-12T00:00:00',按 本地时区解析。
  • 带时区后缀:末尾有 Z(UTC)或 +08:00 等偏移量,如 '2026-05-12T00:00:00+08:00',严格按指定时区解析,跨设备行为最稳定。
避坑提醒:避免直接传入 '2026-5-12'(未补零)、'05-12-2026' 或 '2026-05-12 08:30:00'(空格分隔而非 T)。不同浏览器和 JS 引擎对非标准格式的解析行为不统一,例如 Safari 早期版本会直接将空格分隔或横杠未补零的日期解析为 Invalid Date。如果日期来自用户输入,建议拆分出年月日数字或先标准化为带时区的 ISO 格式。

4. 传入数值分量:精准构造本地时间

new Date(year, monthIndex, day, hours, minutes, seconds, ms) 至少需要传入年份和月份两个参数,其余参数可选(day 默认为 1,时分秒毫秒默认为 0),全部按本地时区构造。

这种写法有三个细节需要记住:

  • 月份从 0 开始:0 代表 1 月,11 代表 12 月。传入 5 月必须写 4。
  • 溢出自动进位或借位:如果传入 day = 0,会自动退回到上个月最后一天;传入 day = 32 会顺延到下个月。利用 new Date(2026, 2, 0) 就能直接拿到 2026 年 2 月的最后一天(28 号)。
  • 两位数年份映射:如果 year 在 0 到 99 之间,会被自动加上 1900,例如 new Date(26, 4, 12) 表示 1926 年而非 2026 年。若要构造公元 0~99 年,需先创建实例再调用 setFullYear()。

如果希望用数值分量构造 UTC 时间而非本地时间,可以配合静态方法 Date.UTC():new Date(Date.UTC(2026, 4, 12, 0, 0, 0))。

5. 传入已有 Date 实例:安全克隆

new Date(existingDate) 会读取原实例的时间戳并生成一个全新对象。由于后续要介绍的 set* 方法会原地修改原对象,做日期计算前先用这种方式克隆一份,可以避免意外改坏原始数据。

实例化后如何验证有效性

当传入无法解析的字符串(如 new Date('abc'))或超出范围的数值时,new Date() 不会抛出异常,而是返回一个特殊的 Invalid Date 对象——它依然属于 Date 类型,但内部时间戳是 NaN。判断一个日期对象是否有效,应使用 Number.isNaN(d.getTime())(返回 true 表示无效)。

JavaScript Date对象常用方法速查与实例化详解
图 2:根据数据来源选择 Date 实例化方式的标准步骤与关键检查点。

三、Date 常用方法速查表

把 Date 的方法按“静态工具、读取分量、修改分量、格式化输出”四组来记,实际写代码时查起来最快。

1. 静态方法(直接通过 Date 调用)

方法 作用与返回值 常见用途与说明
Date.now() 返回当前时间的毫秒时间戳(Number) 计算耗时、生成时间戳参数;比 new Date().getTime() 省去创建对象的开销
Date.parse(str) 解析日期字符串,返回毫秒时间戳;失败返回 NaN 解析规则与 new Date(str) 完全相同,纯校验或只取时间戳时可用
Date.UTC(y, m, ...) 按 UTC 时区把数值分量转成毫秒时间戳 m 同样从 0 开始;常配合 new Date(Date.UTC(...)) 使用

2. 读取时间分量(Getter)

以下列出最常用的本地时间读取方法。若需要读取零时区数值,把 get 换成 getUTC 即可(例如 getUTCFullYear()、getUTCHours())。

方法 返回值范围 / 含义 易错点提醒
getFullYear() 4 位完整年份(如 2026) 不要使用已废弃的 getYear()(2026 年会返回 126)
getMonth() 0 ~ 11(0 代表 1 月) 展示给用户时必须 + 1
getDate() 1 ~ 31(当月第几天) 它才是“几号”,不要和 getDay() 混淆
getDay() 0 ~ 6(0 代表周日) 表示“星期几”,周一到周六分别是 1 ~ 6
getHours() / getMinutes() / getSeconds() 时 0~23、分 0~59、秒 0~59 均为单个整数,不足两位不会自动补 0
getMilliseconds() 0 ~ 999 常用于高精度日志或耗时统计
getTime() / valueOf() 毫秒时间戳;无效日期返回 NaN 两个 Date 比较早晚时可直接用 a.getTime() < b.getTime(),也支持直接 a - b 相减
getTimezoneOffset() UTC 与本地时间的分钟差(UTC - 本地) 正负号容易看反:东八区(UTC+8)返回 -480,而不是 480

3. 修改时间分量(Setter)

set* 系列方法会直接修改当前 Date 实例的内部时间戳,并返回修改后的新毫秒时间戳,而不是返回一个新的 Date 对象。

方法 可传参数 核心行为
setFullYear(y [, m, d]) 年份,可选月、日 可一次设置年月日;对应 UTC 版本为 setUTCFullYear()
setMonth(m [, d]) 月份(0~11),可选日 若原日期为 31 号而目标月不足 31 天,会自动顺延到下个月初
setDate(d) 当月第几天 最稳妥的“加减天数”手段:d.setDate(d.getDate() + 7) 会自动跨月跨年
setHours(h [, m, s, ms]) 小时,可选分、秒、毫秒 常用于把某天重置到零点:d.setHours(0, 0, 0, 0)
setMinutes() / setSeconds() / setMilliseconds() 分/秒/毫秒及更小单位 同样支持超出范围自动进位(如 setSeconds(70) 会让分钟加 1)
setTime(ms) 毫秒时间戳 直接整体替换实例时间,常用于复用同一个 Date 对象
JavaScript Date对象常用方法速查与实例化详解
图 3:日期字段返回值规则对比,以及 setMonth 在月末日期上触发自动顺延的原理。

4. 格式化与字符串转换方法

方法 输出格式示例(基于东八区示例时间) 适用场景
toISOString() "2026-05-12T00:30:00.000Z" 前后端接口传参、日志存储;永远输出 UTC 时间
toJSON() 同 toISOString();无效日期返回 null JSON.stringify() 自动调用的方法
toLocaleString(locale, opts) "2026/5/12 08:30:00"(传 'zh-CN') 按指定语言与格式展示给用户,支持自定义 timeZone
toLocaleDateString() / toLocaleTimeString() "2026/5/12" / "08:30:00" 仅展示本地日期部分或时间部分
toString() "Tue May 12 2026 08:30:00 GMT+0800 (...)" 控制台调试,格式由语言环境决定,不建议用于接口或正则解析
toDateString() / toTimeString() "Tue May 12 2026" / "08:30:00 GMT+0800 (...)" 英文可读调试文本

四、三个常见实战操作写法与验证

掌握上面方法后,日常开发最常遇到的是格式化补零、安全日期加减以及时区展示。下面直接在浏览器控制台或 Node.js 环境中可运行的示例代码,均避开了前面提到的常见陷阱。

操作 1:格式化为本地 YYYY-MM-DD HH:mm:ss

很多新手会直接写 d.toISOString().slice(0, 19).replace('T', ' '),但 toISOString() 输出的是 UTC 时间,在东八区会比本地时间少 8 小时。稳妥的做法是用本地 Getter 配合 String.prototype.padStart(2, '0') 补零:

function formatLocalDateTime(date) {
  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
    throw new TypeError('请传入有效的 Date 实例');
  }
  const pad = (n) => String(n).padStart(2, '0');
  const y = date.getFullYear();
  const m = pad(date.getMonth() + 1);
  const d = pad(date.getDate());
  const hh = pad(date.getHours());
  const mm = pad(date.getMinutes());
  const ss = pad(date.getSeconds());
  return `${y}-${m}-${d} ${hh}:${mm}:${ss}`;
}

const sample = new Date(2026, 4, 12, 8, 5, 3);
console.log(formatLocalDateTime(sample));
示例输出
2026-05-12 08:05:03

操作 2:安全克隆后计算“N 天后”与“月份加减”

加减天数时,先用 new Date(source) 克隆,再调用 setDate(),不会改动原始对象;如果按月加减且希望保留月末对齐(比如 1 月 31 日加 1 个月变成 2 月 28 日而不是 3 月 3 日),需要在修改月份后比对目标日并钳位:

function addDays(source, days) {
  const copy = new Date(source.getTime());
  copy.setDate(copy.getDate() + days);
  return copy;
}

function addMonthsSafe(source, months) {
  const copy = new Date(source.getTime());
  const targetDay = copy.getDate();
  copy.setDate(1); // 先置为 1 号,避免直接 setMonth 时提前溢出
  copy.setMonth(copy.getMonth() + months);
  // 计算目标月份的实际最大天数(下月第 0 天)
  const maxDay = new Date(copy.getFullYear(), copy.getMonth() + 1, 0).getDate();
  copy.setDate(Math.min(targetDay, maxDay));
  return copy;
}

const jan31 = new Date(2026, 0, 31);
console.log(formatLocalDateTime(addDays(jan31, 7)).slice(0, 10));
console.log(formatLocalDateTime(addMonthsSafe(jan31, 1)).slice(0, 10));
console.log(formatLocalDateTime(jan31).slice(0, 10)); // 验证原对象未被修改
示例输出
2026-02-07
2026-02-28
2026-01-31

操作 3:使用 toLocaleString 固定格式与时区展示

如果不想手写拼接函数,toLocaleString() 支持传入语言标记与配置项,并能显式指定 timeZone(如 'Asia/Shanghai')来保证不同地区用户看到统一时区的文本:

const utcMoment = new Date('2026-05-12T00:00:00Z');
const formatted = utcMoment.toLocaleString('zh-CN', {
  timeZone: 'Asia/Shanghai',
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
  hour12: false
});
console.log(formatted);
示例输出
2026/05/12 08:00:00

若需要更高频地批量格式化大量日期列表,建议改用 new Intl.DateTimeFormat('zh-CN', options).format(date),避免每次调用 toLocaleString() 都重新创建格式化器带来的额外开销。

五、方法选择与速查总结

面对具体需求时,可以按下面这张全景速查图快速定位合适的方法,同时核对对应的边界条件。

JavaScript Date对象常用方法速查与实例化详解
图 4:JavaScript Date 四类核心方法速查矩阵与不同场景的选用原则。

如果项目需要处理复杂的时区切换、工作日历或夏令时推算,在原生 Date 之外也可以评估轻量级日期库(如 date-fns、Day.js)或逐步关注现代浏览器推进中的 Temporal API;不过在常规业务里,只要把握住“单时间戳模型、字符串解析时区、month 零基索引、Setter 原地修改”这四条边界,原生 Date 已经足够清晰可靠。

作者最新文章
相关文章
更多