怎么使用dayjs轻量级库格式化JS时间

作者:资源驿站

时间:2026-11-18

浏览:244

本文详细介绍如何使用轻量级库 Day.js 格式化 JavaScript 时间,涵盖安装引入、基础 format 用法、核心占位符速查、中文本地化配置、相对时间插件扩展及高频避坑指南。

文章目录
在 JavaScript 中,原生 Date 对象的格式化操作需要调用多个 get 方法并手动补零,不仅代码冗长且极易出现月份索引偏差。Day.js 是一个仅有 2KB 左右的极简时间处理库,其核心格式化方法为 dayjs(时间源).format('格式模版')。通过声明式占位符替换,只需一行代码即可将当前时间、时间戳、Date 实例或 ISO 字符串转换为任意业务所需的日期时间格式。
怎么使用dayjs轻量级库格式化JS时间
Day.js 格式化核心流转与轻量级架构概览

一、安装与引入 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() 时若不传参数,将自动获取客户端当前系统时间。

怎么使用dayjs轻量级库格式化JS时间
图1:Day.js 时间格式化标准执行链路

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 采用标准化占位符体系,通过声明式模版解决了一致性与补零问题。

怎么使用dayjs轻量级库格式化JS时间
图2:原生 JavaScript Date vs 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 极小体积,原因在于其核心库仅保留了最高频的基础计算与格式化逻辑。对于“中文星期几”、“相对时间”等特性,均以独立语言包和插件的形式按需加载。

怎么使用dayjs轻量级库格式化JS时间
图3:Day.js 本地化语言包与插件扩展装配架构

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 的优雅表达能力。

怎么使用dayjs轻量级库格式化JS时间
图4:Day.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(...),即可兼顾性能、体积与跨浏览器的时间显示稳定性。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章