Vue3时间戳转换器：基于Composition API的复用方案

1. 项目概述

在Web开发中，时间戳的处理是一个高频需求。最近我在重构一个后台管理系统时，发现项目中至少有20处需要将时间戳转换为可读格式的场景。传统的处理方式是在每个组件中重复编写转换逻辑，这不仅增加了代码冗余，也降低了维护效率。于是我用Vue3的Composition API设计了一个可复用的时间戳转换器方案。

这个方案的核心价值在于：

• 统一处理逻辑，避免重复代码
• 支持多种格式输出（如"YYYY-MM-DD"、"刚刚"、"3分钟前"等）
• 自动处理时区问题
• 提供响应式更新能力

2. 核心设计思路

2.1 技术选型分析

在Vue3环境下，我们有几种实现时间戳转换的方案：

1. 过滤器（Filters）：Vue2的常用方案，但Vue3已移除
2. 全局方法：通过app.config.globalProperties挂载
3. Composition函数：利用setup语法实现
4. 自定义指令：适用于DOM操作场景

经过对比测试，我选择了Composition函数方案，原因如下：

• 类型支持完善（配合TypeScript）
• 逻辑封装彻底
• 组合式API的复用性最佳
• 不受模板限制，可在JS逻辑中使用

2.2 架构设计

转换器的核心架构包含三个层次：

1. 基础转换层：使用day.js处理原始时间戳
2. 业务逻辑层：实现相对时间、格式化等业务需求
3. 应用接口层：提供组件和模板使用的API

typescript复制// 架构示意图
[原始时间戳] 
  → [day.js解析] 
  → [业务处理（相对时间/格式化）] 
  → [响应式输出]

3. 完整实现方案

3.1 基础实现

首先安装day.js（比moment.js更轻量）：

bash复制npm install dayjs

创建核心转换函数：

typescript复制// src/utils/time.ts
import dayjs from 'dayjs'
import relativeTime from 'dayjs/plugin/relativeTime'
import 'dayjs/locale/zh-cn'

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

export function formatTimestamp(
  timestamp: number | string,
  format = 'YYYY-MM-DD HH:mm:ss'
): string {
  return dayjs(timestamp).format(format)
}

export function toRelativeTime(timestamp: number | string): string {
  return dayjs(timestamp).fromNow()
}

3.2 Vue3组合式函数封装

创建useTimeHook：

typescript复制// src/composables/useTime.ts
import { ref, watchEffect } from 'vue'
import { formatTimestamp, toRelativeTime } from '@/utils/time'

export function useTimeFormatter() {
  const formattedTime = ref('')
  const relativeTime = ref('')

  const updateTime = (timestamp: number | string) => {
    formattedTime.value = formatTimestamp(timestamp)
    relativeTime.value = toRelativeTime(timestamp)
  }

  return {
    formattedTime,
    relativeTime,
    updateTime
  }
}

3.3 组件中使用示例

vue复制<template>
  <div>
    <p>标准格式：{{ formattedTime }}</p>
    <p>相对时间：{{ relativeTime }}</p>
  </div>
</template>

<script setup>
import { useTimeFormatter } from '@/composables/useTime'

const { formattedTime, relativeTime, updateTime } = useTimeFormatter()

// 假设从API获取数据
const fetchData = async () => {
  const res = await getSomeData()
  updateTime(res.timestamp)
}
</script>

4. 高级功能实现

4.1 自动更新相对时间

对于"3分钟前"这类相对时间，需要定时刷新：

typescript复制export function useAutoUpdateTime(timestamp: number) {
  const relativeTime = ref(toRelativeTime(timestamp))
  
  const update = () => {
    relativeTime.value = toRelativeTime(timestamp)
  }

  const interval = setInterval(update, 60000) // 每分钟更新

  onUnmounted(() => clearInterval(interval))

  return { relativeTime }
}

4.2 全局指令实现

如果需要像Vue2过滤器那样在模板中使用：

typescript复制// src/directives/time.ts
import { formatTimestamp } from '@/utils/time'

export default {
  mounted(el: HTMLElement, binding: DirectiveBinding) {
    const { value, modifiers } = binding
    let format = 'YYYY-MM-DD HH:mm:ss'
    
    if (modifiers.short) {
      format = 'MM-DD HH:mm'
    } else if (modifiers.date) {
      format = 'YYYY-MM-DD'
    }
    
    el.textContent = formatTimestamp(value, format)
  }
}

注册指令：

typescript复制// main.ts
import timeDirective from '@/directives/time'

app.directive('time', timeDirective)

使用示例：

vue复制<template>
  <span v-time="timestamp" />
  <span v-time.date="timestamp" />
  <span v-time.short="timestamp" />
</template>

5. 性能优化方案

5.1 防抖处理

当批量渲染时间数据时：

typescript复制import { debounce } from 'lodash-es'

export function useDebouncedTimeUpdate() {
  const updateTime = debounce((timestamp) => {
    // 更新逻辑
  }, 100)

  return { updateTime }
}

5.2 时区处理

对于国际化项目：

typescript复制import utc from 'dayjs/plugin/utc'
import timezone from 'dayjs/plugin/timezone'

dayjs.extend(utc)
dayjs.extend(timezone)

export function formatWithTimezone(
  timestamp: number,
  timezone: string
): string {
  return dayjs(timestamp).tz(timezone).format()
}

6. 常见问题与解决方案

6.1 时间戳格式问题

问题现象：

• 显示"Invalid Date"
• 时区计算错误

解决方案：

typescript复制function safeFormat(timestamp: unknown): string {
  // 处理字符串时间戳
  if (typeof timestamp === 'string') {
    if (/^\d+$/.test(timestamp)) {
      timestamp = Number(timestamp)
    }
  }
  
  // 处理秒级时间戳
  if (typeof timestamp === 'number' && timestamp < 1e12) {
    timestamp *= 1000
  }
  
  return dayjs(timestamp).isValid() 
    ? dayjs(timestamp).format()
    : '无效时间'
}

6.2 SSR兼容问题

问题现象：

• 服务端渲染时显示时间不匹配
• Hydration不匹配警告

解决方案：

typescript复制import { ref, onMounted } from 'vue'

export function useSSRTime(timestamp: number) {
  const time = ref('')
  
  onMounted(() => {
    time.value = formatTimestamp(timestamp)
  })

  return { time }
}

7. 单元测试方案

使用Vitest编写测试用例：

typescript复制import { describe, it, expect } from 'vitest'
import { formatTimestamp, toRelativeTime } from '@/utils/time'

describe('时间格式化工具', () => {
  const testTimestamp = 1672531200000 // 2023-01-01 00:00:00
  
  it('应正确格式化时间', () => {
    expect(formatTimestamp(testTimestamp))
      .toBe('2023-01-01 00:00:00')
  })
  
  it('应显示相对时间', () => {
    // 模拟当前时间
    vi.useFakeTimers()
    vi.setSystemTime(testTimestamp + 3600000) // +1小时
    
    expect(toRelativeTime(testTimestamp))
      .toBe('1小时前')
    
    vi.useRealTimers()
  })
})

8. 项目集成建议

8.1 在Pinia中的使用

创建全局时间store：

typescript复制// stores/time.ts
import { defineStore } from 'pinia'
import { useTimeFormatter } from '@/composables/useTime'

export const useTimeStore = defineStore('time', () => {
  const { formattedTime, updateTime } = useTimeFormatter()
  
  return { formattedTime, updateTime }
})

8.2 在路由守卫中的应用

记录页面访问时间：

typescript复制router.beforeEach((to, from, next) => {
  const timeStore = useTimeStore()
  timeStore.updateTime(Date.now())
  next()
})

9. 扩展思考

9.1 国际化支持

通过dayjs的多语言支持：

typescript复制import 'dayjs/locale/en'
import 'dayjs/locale/ja'

export function setLocale(lang: string) {
  dayjs.locale(lang)
}

9.2 日期范围处理

实现日期区间格式化：

typescript复制export function formatRange(start: number, end: number): string {
  const startDay = dayjs(start)
  const endDay = dayjs(end)
  
  if (startDay.isSame(endDay, 'day')) {
    return `${startDay.format('YYYY-MM-DD')} ${startDay.format('HH:mm')}-${endDay.format('HH:mm')}`
  }
  
  return `${startDay.format()} - ${endDay.format()}`
}

10. 最终实现效果

在项目中实际应用后：

1. 时间相关代码量减少70%
2. 统一了全站时间显示格式
3. 新增需求只需修改一处代码
4. 测试覆盖率提升至95%+

这个方案特别适合：

• 后台管理系统
• 社交类应用
• 需要频繁展示时间的项目
• 国际化多时区项目