Day.js 基础用法全方位详解

Day.js 基础用法全方位详解

一、Day.js 简介

Day.js 是一个轻量级的 JavaScript 日期处理库，API 设计与 Moment.js 高度兼容，但体积仅有 2KB 左右。它支持链式调用、不可变数据、插件扩展等特性，非常适合现代前端项目。

---

二、安装与引入

1. NPM/Yarn 安装

npm install dayjs
# 或
yarn add dayjs

2. CDN 引入

<script src="https://unpkg.com/dayjs@1.11.10/dayjs.min.js"></script>

---

三、创建日期对象

Day.js 支持多种方式创建日期对象：

import dayjs from 'dayjs';

// 当前时间
const now = dayjs();

// 指定日期字符串（支持多种格式）
const d1 = dayjs('2024-06-01');
const d2 = dayjs('2024/06/01 12:30:00');

// 指定时间戳（毫秒）
const d3 = dayjs(1717200000000);

// 通过原生 Date 对象
const d4 = dayjs(new Date());

// 通过数组（不推荐，Day.js 不直接支持）

注意：

• Day.js 默认解析 ISO 8601 格式，其他格式建议配合 customParseFormat 插件。
• 月份从 1 开始，和原生 Date 不同。

---

四、格式化日期

使用 .format() 方法自定义日期输出：

const date = dayjs('2024-06-01 15:30:45');
console.log(date.format('YYYY-MM-DD HH:mm:ss')); // 2024-06-01 15:30:45
console.log(date.format('dddd, MMMM D, YYYY'));  // Saturday, June 1, 2024
console.log(date.format('YYYY年M月D日'));         // 2024年6月1日

常用格式化符号：

符号	含义	示例
YYYY	年	2024
MM	月（01-12）	06
M	月（1-12）	6
DD	日（01-31）	01
D	日（1-31）	1
HH	小时（00-23）	15
mm	分钟（00-59）	30
ss	秒（00-59）	45
dddd	星期几	Saturday

---

五、解析日期（字符串转日期）

Day.js 默认只支持 ISO 8601 格式和部分常见格式。如果需要解析自定义格式，需引入 customParseFormat 插件：

import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);

const d = dayjs('2024年06月01日', 'YYYY年MM月DD日');
console.log(d.format()); // 2024-06-01T00:00:00+08:00

---

六、日期运算

1. 加法 .add()

const date = dayjs('2024-06-01');
console.log(date.add(1, 'day').format());    // 2024-06-02
console.log(date.add(2, 'month').format());  // 2024-08-01
console.log(date.add(1, 'year').format());   // 2025-06-01

2. 减法 .subtract()

console.log(date.subtract(7, 'day').format()); // 2024-05-25

3. 支持的单位

• year / y
• month / M
• week / w
• day / d
• hour / h
• minute / m
• second / s
• millisecond / ms

---

七、获取日期信息

const date = dayjs('2024-06-01 15:30:45');
console.log(date.year());    // 2024
console.log(date.month());   // 5 (注意：0 表示 1 月)
console.log(date.date());    // 1
console.log(date.day());     // 6 (0 表示周日)
console.log(date.hour());    // 15
console.log(date.minute());  // 30
console.log(date.second());  // 45

---

八、设置日期信息

let date = dayjs('2024-06-01 15:30:45');
date = date.year(2025);
date = date.month(0); // 0 表示 1 月
date = date.date(10);
date = date.hour(8).minute(0).second(0);
console.log(date.format('YYYY-MM-DD HH:mm:ss')); // 2025-01-10 08:00:00

---

九、日期比较

const d1 = dayjs('2024-06-01');
const d2 = dayjs('2024-06-10');

console.log(d1.isBefore(d2)); // true
console.log(d2.isAfter(d1));  // true
console.log(d1.isSame('2024-06-01')); // true

// 支持单位比较
console.log(d1.isSame(d2, 'month')); // true
console.log(d1.isSame(d2, 'day'));   // false

---

十、获取时间戳与原生 Date

const date = dayjs('2024-06-01 15:30:45');
console.log(date.valueOf()); // 毫秒时间戳
console.log(date.unix());    // 秒时间戳
console.log(date.toDate());  // 转为原生 Date 对象

---

十一、判断有效性与闰年

console.log(dayjs('2024-02-29').isValid()); // true
console.log(dayjs('2023-02-29').isValid()); // false

// 判断闰年（需引入 isLeapYear 插件）
import isLeapYear from 'dayjs/plugin/isLeapYear';
dayjs.extend(isLeapYear);

console.log(dayjs('2024-01-01').isLeapYear()); // true

---

十二、获取月初、月末、年初、年末

console.log(dayjs().startOf('month').format('YYYY-MM-DD')); // 月初
console.log(dayjs().endOf('month').format('YYYY-MM-DD'));   // 月末
console.log(dayjs().startOf('year').format('YYYY-MM-DD'));  // 年初
console.log(dayjs().endOf('year').format('YYYY-MM-DD'));    // 年末

---

十三、国际化（本地化）

Day.js 默认是英文，如需中文等其他语言，需引入 locale：

import 'dayjs/locale/zh-cn';
dayjs.locale('zh-cn');

console.log(dayjs().format('dddd')); // 星期几（中文）

---

十四、常用插件推荐

Day.js 通过插件机制扩展功能，常用插件有：

• customParseFormat：自定义解析格式
• isLeapYear：判断闰年
• relativeTime：相对时间（如“3天前”）
• duration：时间段处理
• advancedFormat：更多格式化符号
• weekday/weekOfYear/isoWeek：周相关操作

示例：相对时间

import relativeTime from 'dayjs/plugin/relativeTime';
dayjs.extend(relativeTime);

console.log(dayjs().from(dayjs('2024-05-01'))); // 1 个月前
console.log(dayjs('2024-05-01').fromNow());     // 1 个月前

---

十五、不可变性与链式调用

Day.js 的所有操作都是不可变的，每次操作都会返回一个新的 Day.js 对象：

const d1 = dayjs('2024-06-01');
const d2 = d1.add(1, 'day');
console.log(d1.format()); // 2024-06-01
console.log(d2.format()); // 2024-06-02

---

十六、与 Moment.js 的区别

• 体积更小，性能更高
• API 设计高度兼容
• 插件机制更灵活
• 默认不支持链式操作的副作用（不可变）

---

十七、常见坑与注意事项

1. 月份从 0 开始：date.month() 返回 0 表示 1 月，和原生 Date 一致。
2. 解析自定义格式需插件：非 ISO 格式字符串需 customParseFormat 插件。
3. 链式调用不可变：每次操作返回新对象，原对象不变。
4. 本地化需手动引入：如需中文等本地化，需引入对应 locale 文件。