Vue 3 中如何封装 dayjs 统一日期格式化?

来源:站长源码作者:叶知晏头衔:草根站长
导读:本期聚焦于叶知晏创作的《Vue 3 中如何封装 dayjs 统一日期格式化?》,敬请观看详情。为什么已经引入了 dayjs,组件里还是反复出现各种日期格式化调用?日期处理看似简单,一旦涉及时区、默认语言、空值兜底和统一输出格式,分散调用会迅速增加维护成本。本文从 Vue 3 的工具库设计角度拆解 dayjs 封装思路:先梳理 dayjs 不可变对象和链式 API 的特性,再给出一个包含初始化配置、常用格式化函数、时间差计算的 utils 封装示例;接着演示如何在组件和组合式函数中复用,以及通过全局属性简化调用。文章还会说明 dayjs 的插件按需加载、中文 locale 配置和避免响应式丢失等细节,帮助你建立一套稳定的日期处理规范。

在 Vue 3 项目里处理日期和时间,最忌讳的就是在业务组件中到处调用 dayjs().format()。这种方式在小型项目里看不出问题,一旦出现产品级需求,比如统一显示为 2024/01/05 09:30 或处理相对时间,散落的格式化代码就会成为维护负担。二次封装 dayjs 并不是多此一举,而是把格式、语言、时区和异常兜底集中起来。下面从工具模块设计、组合式函数接入、格式化规则三个层面展开。

Vue 3 中如何封装 dayjs 统一日期格式化?

一、为什么选择 dayjs 以及为什么需要二次封装

Vue 3 项目选择 dayjs 的首要原因是体积。dayjs 核心包约 2KB,而 moment 打包后要大得多,并且 moment 官方已不再推荐用于新项目。dayjs 的 API 设计与 moment 高度相似,迁移成本低,同时它是一个不可变库,每次链式操作都会返回新的日期对象,不会污染原始值。这个特性在 Vue 3 的响应式数据里尤为重要,因为原始日期对象的修改不容易被追踪,反而容易产生隐性 bug。

二次封装的核心不是包一层 API 那么简单。它要解决三个问题:第一,统一默认输出格式,避免不同页面出现 2024-1-5、2024/01/05、2024年1月5日 等混用;第二,集中配置中文语言包和插件,不让每个组件重复引入;第三,统一空值和无效日期的兜底策略。只要把这些逻辑放在一个模块里,后续调整时只改一处即可。

例如安装依赖后,先在工具文件里引入 dayjs,并按需加载相对时间插件 relativeTime 和 UTC 插件 utc。插件只有在 dayjs.extend() 注册后才会生效,这样可以保持运行时体积可控。

npm install dayjs

二、封装一个可复用的日期工具模块

封装日期工具模块时,建议把配置与函数分开。配置文件负责初始化 dayjs,包括 dayjs.extend() 和 dayjs.locale('zh-cn')。业务函数只做两件事:接收一个可能的日期值,先用 dayjs(value) 转换,再判断 isValid(),有效则格式化,无效则返回空字符串或指定占位符。这样可以避免界面出现英文的 Invalid Date,也能让调用方省去大量判断。

以 formatDate 为例,不要直接 return dayjs(value).format(pattern),因为当 value 是 null、空字符串或无效时间时,format() 会抛出异常或返回奇怪结果。先验证再格式化,才能保证组件渲染稳定。另一个常用函数是 formatRelative,它依赖 relativeTime 插件,配合中文 locale 会显示几分钟前、三天前等自然语言。

下面是一份相对完整的模块代码,包含日期、日期时间、相对时间和天数差计算。导出时同时提供具名函数和默认对象,既方便按需引入,也可以在需要时整体导入。

import dayjs from 'dayjs'
import relativeTime from 'dayjs/plugin/relativeTime'
import utc from 'dayjs/plugin/utc'
import 'dayjs/locale/zh-cn'

dayjs.extend(relativeTime)
dayjs.extend(utc)
dayjs.locale('zh-cn')

export const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD'
export const DEFAULT_DATETIME_FORMAT = 'YYYY-MM-DD HH:mm:ss'

export function isValidDate(value) {
  return dayjs(value).isValid()
}

export function formatDate(value, pattern = DEFAULT_DATE_FORMAT) {
  const date = dayjs(value)
  return date.isValid() ? date.format(pattern) : ''
}

export function formatDateTime(value) {
  return formatDate(value, DEFAULT_DATETIME_FORMAT)
}

export function formatRelative(value) {
  const date = dayjs(value)
  return date.isValid() ? date.fromNow() : ''
}

export function diffDays(start, end) {
  const startDay = dayjs(start)
  const endDay = dayjs(end)
  if (!startDay.isValid() || !endDay.isValid()) return 0
  return endDay.diff(startDay, 'day')
}

export default {
  formatDate,
  formatDateTime,
  formatRelative,
  diffDays,
  isValidDate
}

三、在 Vue 3 组件与组合式函数中使用

在 Vue 3 组件中使用这些函数时,推荐用 <script setup> 语法直接导入。日期展示通常与 props 或接口返回的字符串绑定,所以可以用 computed 把格式化结果缓存起来,避免模板每次更新都重新执行一次格式化。尤其是相对时间,它依赖当前时间,建议在需要更新时手动触发,不要把它放在频繁刷新的 computed 中。

另一个常见做法是把 formatDate 挂载到 app.config.globalProperties 上,这样可以在模板中直接用 $formatDate 调用。这个方式对选项式 API 代码比较友好,但在组合式 API 中无法通过 this 直接访问,需要结合 getCurrentInstance 或者干脆显式导入。个人更建议显式导入,因为类型提示和依赖关系更清晰。

下面的组件示例接收一个创建时间字符串,展示标准日期和相对时间。注意不要把 formatRelative 的返回值保存到响应式变量后再反复赋值,而是用 computed 直接根据原始数据生成展示值。

<script setup>
import { computed } from 'vue'
import { formatDate, formatRelative } from '@/utils/date'

const props = defineProps({
  createdAt: {
    type: String,
    required: true
  }
})

const displayDate = computed(() => formatDate(props.createdAt, 'YYYY年MM月DD日'))
const relativeText = computed(() => formatRelative(props.createdAt))
</script>

<template>
  <div>
    <span>{{ displayDate }}</span>
    <span>{{ relativeText }}</span>
  </div>
</template>

四、格式化模板与细节避坑

dayjs 的格式化 token 不难记,但有几个地方容易踩坑。年份使用大写 YYYY,月份使用大写 MM,分钟使用小写 mm。如果写成 yyyy-mm-dd,dayjs 不会按预期输出,因为 yyyy 不是有效 token,会保持原样。常用组合可以参考下面表格。

格式输出示例说明
YYYY-MM-DD2024-01-05标准日期
YYYY-MM-DD HH:mm:ss2024-01-05 09:30:45标准日期时间
YYYY年MM月DD日2024年01月05日中文日期
YYYY/MM/DD HH:mm2024/01/05 09:30短日期时间

国际化方面,必须显式 import 'dayjs/locale/zh-cn' 并调用 dayjs.locale('zh-cn'),否则 fromNow() 输出的内容仍然是英文。对于需要处理 UTC 时间的场景,可以先 dayjs.utc(value) 再 .local() 转成本地时间。要注意 dayjs 内置的 utc 插件不能处理任意时区名称,例如想用 Asia/Shanghai,需要额外的 timezone 插件,这会增加一定体积,所以只在真正需要时引入。

响应式数据是 Vue 3 中很容易被忽略的日期坑。不要直接把 dayjs 对象放进 reactive 或 ref 中,因为 Vue 的代理会改变对象行为,可能导致方法失效或者触发不必要的更新。推荐在数据层保存 ISO 字符串或时间戳,展示层再通过工具函数转换。下面是一个错误和推荐的对比。

import { reactive } from 'vue'
import dayjs from 'dayjs'

// 不推荐:dayjs 对象被 reactive 代理
const state = reactive({
  time: dayjs()
})

// 推荐:保存原始字符串或时间戳
const betterState = reactive({
  time: new Date().toISOString()
})

除了这些细节,封装后的日期模块应当保持纯函数特性:同一输入永远得到同一输出,不要在内部修改全局状态。这样在单元测试中也能直接断言格式化结果。若项目中有多种日期格式需求,可以继续在模块里扩展 formatMonth、formatWeek 等函数,不必在每个页面复制模板字符串。

Vue 3dayjs日期格式化修改时间:2026-10-29 01:27:47

免责声明:已尽一切努力确保本网站所含信息的准确性。网站作品多为原创整理与精心创作,观点力求客观中立。本站旨在免费分享,内容仅供个人学习、研究或参考使用。若引用了第三方作品,版权归原作者所有。如内容涉及您的权益,请联系我们进行处理Email:chomcom@qq.com。
引用或转载本作品时,请注明当前出处:https://www.ipipp.com/html/1029/71302.html,基于非商业用途的前提下,欢迎转载或二创本作品。
内容垂直聚焦
专注技术核心技术栏目,确保每篇文章深度聚焦于实用技能。从代码技巧到架构设计,为用户提供无干扰的纯技术知识沉淀,精准满足专业提升需求。
知识结构清晰
覆盖从开发到部署的全链路。AI、前端、编程、数据库、服务器、建站、系统层层递进,构建清晰学习路径,帮助用户系统化掌握开发与运维所需的核心技术。
深度技术解析
拒绝泛泛而谈,深入技术细节与实践难点。无论是数据库优化还是服务器配置,均结合真实场景与代码示例进行剖析,致力于提供可直接应用于工作的解决方案。
专业领域覆盖
精准对应开发生命周期。从前端界面到后端编程,从数据库操作到服务器运维,形成完整闭环,一站式满足全栈工程师和运维人员的技术需求。
即学即用高效
内容强调实操性,步骤清晰、代码完整。用户可根据教程直接复现和应用于自身项目,显著缩短从学习到实践的距离,快速解决开发中的具体问题。
持续更新保障
专注既定技术方向进行长期、稳定的内容输出。确保各栏目技术文章持续更新迭代,紧跟主流技术发展趋势,为用户提供经久不衰的学习价值。