当前位置：首页 > news >正文

Day.js 使用文档

news 2025/10/29 11:10:57

一、什么是 Day.js？

Day.js 是一个轻量级的 JavaScript 日期处理库，API 设计与 Moment.js 高度一致，但体积仅 2KB 左右（远小于 Moment.js 的 24KB+），且支持 tree-shaking，非常适合对体积敏感的项目。它专注于日期解析、格式化、计算等核心功能，同时保持了简洁的 API 和良好的兼容性。

二、安装与引入

1. 安装

通过 npm 或 yarn 安装：

npm install dayjs --save
# 或
yarn add dayjs

2. 引入

在项目中直接引入即可使用核心功能：

import dayjs from 'dayjs'

三、核心概念：Day.js 对象

Day.js 的所有操作都围绕「Day.js 对象」进行。该对象是不可变的（immutable），即任何修改操作（如加减时间、设置日期）都会返回一个新的 Day.js 对象，原对象不会被改变。

创建 Day.js 对象的常用方式：

// 1. 当前时间
const now = dayjs()// 2. 从字符串创建（支持 ISO 格式、YYYY-MM-DD 等）
const date1 = dayjs('2023-10-01')
const date2 = dayjs('2023-10-01T12:30:00')// 3. 从时间戳创建（毫秒）
const date3 = dayjs(1696108800000) // 对应 2023-10-01 00:00:00// 4. 从 Date 对象创建
const date4 = dayjs(new Date(2023, 9, 1)) // 注意：Month 是 0 基（9 对应 10月）// 5. 复制现有 Day.js 对象
const date5 = dayjs(now) // 复制 now 对象

四、常用 API 操作

1. 格式化日期（format）

将 Day.js 对象转为指定格式的字符串，支持多种占位符：

const date = dayjs('2023-10-01 12:30:45')// 常用格式
date.format('YYYY-MM-DD') // '2023-10-01'
date.format('YYYY年MM月DD日') // '2023年10月01日'
date.format('HH:mm:ss') // '12:30:45'
date.format('YYYY-MM-DD HH:mm:ss') // '2023-10-01 12:30:45'
date.format('ddd') // 'Sun'（星期缩写，依赖本地化插件）
date.format('X') // 1696149045（秒级时间戳）
date.format('x') // 1696149045000（毫秒级时间戳）

常用占位符说明：

YYYY：4位年份（如 2023）
MM：2位月份（01-12）
DD：2位日期（01-31）
HH：24小时制小时（00-23）
hh：12小时制小时（01-12）
mm：分钟（00-59）
ss：秒（00-59）
X：秒级时间戳
x：毫秒级时间戳

2. 解析与验证（isValid）

检查日期是否有效（避免无效日期如 2023-02-30）：

dayjs('2023-02-30').isValid() // false（2月没有30日）
dayjs('2023-13-01').isValid() // false（月份超出范围）
dayjs('2023-10-01').isValid() // true

3. 时间计算（加减操作）

通过 add 和 subtract 对日期进行增减，支持年、月、日等单位：

const now = dayjs('2023-10-01')// 加 1 年
now.add(1, 'year').format('YYYY-MM-DD') // '2024-10-01'// 减 1 个月
now.subtract(1, 'month').format('YYYY-MM-DD') // '2023-09-01'// 加 7 天
now.add(7, 'day').format('YYYY-MM-DD') // '2023-10-08'// 加 30 分钟
now.add(30, 'minute').format('HH:mm') // 假设原时间为 00:00 → '00:30'

支持的单位： year（年）、month（月）、day（日）、hour（时）、minute（分）、second（秒）、millisecond（毫秒）。

4. 时间比较（diff）

计算两个日期的差值：

const date1 = dayjs('2023-10-01')
const date2 = dayjs('2023-10-08')// 计算相差的天数
date2.diff(date1, 'day') // 7// 计算相差的小时数
date2.diff(date1, 'hour') // 168（7×24）// 不指定单位时，默认返回毫秒数
date2.diff(date1) // 604800000（7×24×60×60×1000）

5. 获取/设置日期部分（get/set）

获取或修改日期的年、月、日等部分：

const date = dayjs('2023-10-01 12:30:45')// 获取
date.year() // 2023（年份）
date.month() // 9（月份，0 基，10月对应 9）
date.date() // 1（日期）
date.hour() // 12（小时）
date.minute() // 30（分钟）
date.second() // 45（秒）// 设置（返回新对象）
date.year(2024).format('YYYY') // '2024'
date.month(10).format('MM') // '11'（设置为 10 → 11月）
date.date(15).format('DD') // '15'

6. 其他常用操作

判断是否在另一个日期之前/之后/相同：

const a = dayjs('2023-10-01')
const b = dayjs('2023-10-02')a.isBefore(b) // true（a 在 b 之前）
a.isAfter(b) // false（a 在 b 之后）
a.isSame(b, 'day') // false（日期不同）
a.isSame(dayjs('2023-10-01 12:00'), 'day') // true（同一天）

获取起始/结束时间：

const date = dayjs('2023-10-01 12:30:45')date.startOf('day').format('HH:mm:ss') // '00:00:00'（当天开始）
date.endOf('month').format('YYYY-MM-DD') // '2023-10-31'（当月结束）

转换为原生 Date 对象：

const date = dayjs('2023-10-01')
date.toDate() // 原生 Date 对象：Sun Oct 01 2023 00:00:00 GMT+0800

五、插件扩展

Day.js 核心功能简洁，可通过插件扩展额外能力（如本地化、相对时间计算等）。

1. 本地化（Locale）

默认显示英文，需引入对应语言包实现中文显示：

import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn' // 引入中文包dayjs.locale('zh-cn') // 全局设置为中文dayjs('2023-10-01').format('dddd') // '星期日'
dayjs().format('MMMM') // '十月'

2. 相对时间（RelativeTime）

计算「多久前」「多久后」（需引入插件）：

import dayjs from 'dayjs'
import relativeTime from 'dayjs/plugin/relativeTime'dayjs.extend(relativeTime) // 扩展插件dayjs('2023-10-01').fromNow() // 假设当前是 2023-10-08 → '7天前'
dayjs().add(3, 'day').fromNow() // '3天后'