本文详细介绍如何使用轻量级库 Day.js 格式化 JavaScript 时间,涵盖安装引入、基础 format 用法、核心占位符速查、中文本地化配置、相对时间插件扩展及高频避坑指南。
怎么使用dayjs轻量级库格式化JS时间
时间:2026-11-18
浏览:244
文章目录
dayjs(时间源).format('格式模版')。通过声明式占位符替换,只需一行代码即可将当前时间、时间戳、Date 实例或 ISO 字符串转换为任意业务所需的日期时间格式。
一、安装与引入 Day.js
Day.js 支持现代前端工程化项目(如 Vue、React、Node.js 服务端)以及传统页面直接通过 CDN 脚本引入。
1. 工程化项目(NPM / Yarn / PNPM)
在终端项目根目录下执行安装命令:
# 使用 npm 安装
npm install dayjs
# 或使用 pnpm 安装
pnpm add dayjs
安装完成后,在 JavaScript 或 TypeScript 代码中按模块规范引入:
// ES Module 规范(Vue、React、Vite、Webpack)
import dayjs from 'dayjs';
// CommonJS 规范(Node.js 原生脚本)
const dayjs = require('dayjs');
2. 浏览器页面直接引入(CDN)
对于无需打包工具的原生 HTML 页面,可在 <head> 或 <body> 底部加入 CDN 链接,全局对象 dayjs 会自动挂载到 window 上:
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
<script>
console.log(dayjs().format('YYYY-MM-DD'));
</script>
二、基础格式化流程与核心用法
使用 Day.js 格式化时间遵循“解析输入源 → 调用 format 方法 → 获得结果字符串”的标准模式。调用 dayjs() 时若不传参数,将自动获取客户端当前系统时间。
1. 常用时间源的包装解析
dayjs() 函数具备强大的宽容解析能力,能够接收多种类型的时间入参:
// 1. 当前时间
const now = dayjs();
// 2. 原生 Date 对象
const fromDate = dayjs(new Date(2026, 10, 17, 14, 30));
// 3. 13 位毫秒级时间戳
const fromTimestamp = dayjs(1763361000000);
// 4. ISO 8601 标准字符串
const fromISO = dayjs('2026-11-17T14:30:00.000Z');
2. format() 默认与模版输出
如果不给 .format() 传递任何参数,Day.js 将输出包含时区的 ISO 8601 格式字符串。传入格式化模版后,内部引擎会自动匹配占位符并替换为具体数字:
const now = dayjs('2026-11-17 15:08:09');
// 无参数默认输出
console.log(now.format());
// 示例输出:2026-11-17T15:08:09+08:00
// 格式化为年月日
console.log(now.format('YYYY-MM-DD'));
// 示例输出:2026-11-17
// 格式化为完整日期加 24 小时制时间
console.log(now.format('YYYY-MM-DD HH:mm:ss'));
// 示例输出:2026-11-17 15:08:09
三、核心占位符速查与原生对比
原生 JavaScript 的 Date.prototype.getMonth() 返回 0~11,且各位数字不足两位时需手工使用 padStart(2, '0') 填充,不仅繁琐而且容易遗漏。Day.js 采用标准化占位符体系,通过声明式模版解决了一致性与补零问题。
| 类别 | 占位符 | 说明 | 示例输出 |
|---|---|---|---|
| 年份 | YYYY |
完整 4 位年份 | 2026 |
YY |
后 2 位年份 | 26 | |
| 月份 | MM |
2 位数字月份(自动补零 01-12) | 11 或 05 |
M |
1 位或 2 位月份(不补零 1-12) | 11 或 5 | |
| 日期 | DD |
2 位数字日期(自动补零 01-31) | 17 或 03 |
D |
1 位或 2 位日期(不补零 1-31) | 17 或 3 | |
| 24小时制 | HH |
2 位小时(00-23) | 09 或 15 |
H |
1 位或 2 位小时(0-23) | 9 或 15 | |
| 12小时制 | hh |
2 位小时(01-12) | 03 |
h |
1 位或 2 位小时(1-12) | 3 | |
| 分钟 | mm |
2 位分钟(自动补零 00-59) | 08 |
m |
1 位或 2 位分钟(0-59) | 8 | |
| 秒数 | ss |
2 位秒钟(自动补零 00-59) | 05 |
s |
1 位或 2 位秒钟(0-59) | 5 | |
| 毫秒 | SSS |
3 位毫秒数(000-999) | 420 |
转义字符的保护(方括号)
如果在格式化字符串中包含具有特殊含义的英文字母(如 Y、M、D、H、s 等),Day.js 会将它们视为占位符进行替换。若希望原样输出这些字符,必须使用一对中括号 [...] 将其包裹:
const time = dayjs('2026-11-17 15:30:00');
// 错误写法:前缀中的 'Y' 与 'H' 会被解析并替换成数字
console.log(time.format('Year: YYYY, Hour: HH'));
// 示例输出:2026ear: 2026, 15our: 15 (发生异常篡改)
// 正确写法:使用中括号包裹纯文本单词
console.log(time.format('[Year:] YYYY, [Hour:] HH'));
// 示例输出:Year: 2026, Hour: 15
四、进阶格式化:本地化语言包与扩展插件
Day.js 之所以能保持 2KB 极小体积,原因在于其核心库仅保留了最高频的基础计算与格式化逻辑。对于“中文星期几”、“相对时间”等特性,均以独立语言包和插件的形式按需加载。
1. 中文语言包(格式化星期几)
默认情况下,Day.js 使用英文输出星期占位符 dddd(例如 Tuesday)。如需输出“星期二”或“周二”,需引入中文语言包 zh-cn 并激活:
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn'; // 引入中文包
// 全局切换为中文环境
dayjs.locale('zh-cn');
const date = dayjs('2026-11-17 15:00:00');
// 格式化中文星期
console.log(date.format('YYYY年MM月DD日 dddd'));
// 示例输出:2026年11月17日 星期二
console.log(date.format('YYYY-MM-DD (dd)'));
// 示例输出:2026-11-17 (二)
2. 相对时间插件(relativeTime)
在论坛、社交网络或通知中心中,经常需要将绝对时间格式化为“3分钟前”、“2小时前”或“刚刚”。借助 relativeTime 插件可以便捷实现:
import dayjs from 'dayjs';
import relativeTime from 'dayjs/plugin/relativeTime';
import 'dayjs/locale/zh-cn';
// 注册插件与本地化配置
dayjs.extend(relativeTime);
dayjs.locale('zh-cn');
const pastTime = dayjs().subtract(15, 'minute');
console.log(pastTime.fromNow());
// 示例输出:15 分钟前
const futureTime = dayjs().add(2, 'day');
console.log(futureTime.fromNow());
// 示例输出:2 天内
五、常见问题与避坑指南
1. 占位符大小写混淆(MM 与 mm,DD 与 dd)
这是时间格式化中最容易发生的隐蔽错误:
- 月份 vs 分钟:
MM(大写)表示两位月份,mm(小写)表示两位分钟。误写为YYYY-mm-DD将导致月份位置错误显示为当前的分钟数。 - 日期 vs 星期:
DD(大写)表示天数(01-31),dd(小写)在未设置语言包时表示星期缩写(如 Mo, Tu)。 - 小时制式:
HH(大写)表示 24 小时制(00-23),hh(小写)表示 12 小时制(01-12)。
2. 10位与13位时间戳解析入口
后端接口有时返回 10 位以秒为单位的 Unix 时间戳,有时返回 13 位毫秒时间戳。
// 错误示范:将 10 位时间戳直接丢入 dayjs()
dayjs(1763361000).format('YYYY-MM-DD');
// 错误结果:1970-01-21(因为被当作仅 176 万毫秒处理)
// 正确做法:10 位秒级时间戳使用 dayjs.unix()
dayjs.unix(1763361000).format('YYYY-MM-DD HH:mm:ss');
// 正确结果:2025-11-17 14:30:00
// 13 位毫秒时间戳直接使用 dayjs()
dayjs(1763361000000).format('YYYY-MM-DD HH:mm:ss');
3. 不可变数据(Immutable)特性
与老旧的 Moment.js 会原地修改原始实例不同,Day.js 的所有运算(如 .add()、.subtract())均返回一个全新的 Dayjs 对象,原有实例不受影响。这意味着在做格式化链式计算时,必须接收返回值:
const base = dayjs('2026-11-17');
base.add(1, 'day');
console.log(base.format('YYYY-MM-DD'));
// 示例输出:2026-11-17 (原对象不会改变)
const tomorrowStr = base.add(1, 'day').format('YYYY-MM-DD');
console.log(tomorrowStr);
// 示例输出:2026-11-18 (链式调用后格式化新实例)
六、全篇总结与常用格式速查
掌握 Day.js 时间格式化,本质是建立“确定时间类型 → 选定格式化模版 → 输出业务所需格式”的思维路径。Day.js 兼顾了原生 API 的极致体积与类 Moment.js 的优雅表达能力。
| 业务场景 | 推荐格式模版 | 代码调用示例 |
|---|---|---|
| 标准日期与时间 | YYYY-MM-DD HH:mm:ss |
dayjs().format('YYYY-MM-DD HH:mm:ss') |
| 仅年月日(纯日期) | YYYY-MM-DD |
dayjs().format('YYYY-MM-DD') |
| 仅时分秒(时间点) | HH:mm:ss |
dayjs().format('HH:mm:ss') |
| 带毫秒的审计日志 | YYYY-MM-DD HH:mm:ss.SSS |
dayjs().format('YYYY-MM-DD HH:mm:ss.SSS') |
| 面向中文用户排版 | YYYY年MM月DD日 HH:mm |
dayjs().format('YYYY年MM月DD日 HH:mm') |
| 导出报表/备份文件名 | YYYYMMDD_HHmmss |
dayjs().format('YYYYMMDD_HHmmss') |
| 12小时制带上下午 | YYYY-MM-DD hh:mm A |
dayjs().format('YYYY-MM-DD hh:mm A') |
按照上述规范,在项目中统一时间工具函数或在视图组件中直接调用 dayjs(date).format(...),即可兼顾性能、体积与跨浏览器的时间显示稳定性。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。