日期工具 (date.ts)
日期工具类,提供日期格式化、转换、计算的通用工具函数。自动兼容两种格式语法:yyyy-MM-dd HH:mm:ss
和 YYYY-MM-DD HH:mm:ss
。
📖 概述
日期工具库包含以下功能类别:
- 日期格式化:将日期转换为特定格式的字符串
- 日期解析:将字符串解析为日期对象
- 当前时间获取:获取当前时间的各种格式
- 日期范围获取:获取特定时间范围
- 日期计算:计算日期之间的关系和差值
- 辅助函数:数字补零等辅助功能
🎨 日期格式化
formatDate
日期格式化,自动兼容两种格式语法。
typescript
formatDate(
time: Date | string | number,
pattern: string = 'yyyy-MM-dd HH:mm:ss'
): string
参数:
time
- 日期对象、字符串或时间戳pattern
- 格式化模式,默认为 'yyyy-MM-dd HH:mm:ss'
支持的格式化字符:
yyyy/YYYY
- 四位年份MM
- 两位月份(01-12)M
- 月份(1-12)dd/DD
- 两位日期(01-31)d/D
- 日期(1-31)HH
- 两位小时(00-23)H
- 小时(0-23)mm
- 两位分钟(00-59)m
- 分钟(0-59)ss
- 两位秒数(00-59)s
- 秒数(0-59)w
- 星期(日-六)
返回值:
string
- 格式化后的日期字符串
示例:
typescript
const now = new Date('2023-01-15 14:30:45')
// 基本格式化
formatDate(now) // "2023-01-15 14:30:45"
formatDate(now, 'yyyy-MM-dd') // "2023-01-15"
formatDate(now, 'YYYY-MM-DD') // "2023-01-15" (兼容语法)
formatDate(now, 'MM/dd/yyyy') // "01/15/2023"
formatDate(now, 'yyyy年MM月dd日') // "2023年01月15日"
// 时间格式化
formatDate(now, 'HH:mm:ss') // "14:30:45"
formatDate(now, 'H:m:s') // "14:30:45"
// 星期格式化
formatDate(now, 'yyyy-MM-dd w') // "2023-01-15 日"
// 时间戳格式化
formatDate(1673766645000) // "2023-01-15 14:30:45"
formatDate('1673766645') // "2023-01-15 14:30:45" (10位时间戳)
formatTableDate
表格时间格式化,专门用于表格单元格的时间显示。
typescript
formatTableDate(
cellValue: string,
pattern: string = 'yyyy-MM-dd HH:mm:ss'
): string
参数:
cellValue
- 单元格时间值pattern
- 日期格式
返回值:
string
- 格式化后的时间字符串
示例:
typescript
// 表格数据格式化
formatTableDate('2023-01-15T14:30:45.000Z') // "2023-01-15 14:30:45"
formatTableDate('2023-01-15T14:30:45.000Z', 'MM/dd') // "01/15"
formatDay
日期格式化简化版,只返回年月日。
typescript
formatDay(time: Date | string | number): string
参数:
time
- 日期
返回值:
string
- 格式化后的年月日字符串(yyyy-MM-dd)
示例:
typescript
formatDay(new Date()) // "2023-01-15"
formatDay('2023-01-15 14:30:45') // "2023-01-15"
formatDay(1673766645000) // "2023-01-15"
formatRelativeTime
相对时间格式化,显示相对于当前时间的描述。
typescript
formatRelativeTime(time: string | number, option?: string): string
参数:
time
- 时间戳(秒或毫秒)option
- 可选格式化模式(当时间超过2天时使用)
返回值:
string
- 相对时间字符串
示例:
typescript
const now = Date.now()
formatRelativeTime(now / 1000) // "刚刚"
formatRelativeTime(now / 1000 - 30) // "刚刚"
formatRelativeTime(now / 1000 - 1800) // "30分钟前"
formatRelativeTime(now / 1000 - 7200) // "2小时前"
formatRelativeTime(now / 1000 - 86400) // "1天前"
formatRelativeTime(now / 1000 - 172800) // "1月15日14时30分"(超过2天显示具体时间)
// 使用自定义格式
formatRelativeTime(now / 1000 - 172800, 'yyyy-MM-dd') // "2023-01-13"
formatDateRange
格式化日期范围为字符串。
typescript
formatDateRange(
dateRange: [Date, Date],
separator: string = '~',
format: string = 'yyyy-MM-dd'
): string
参数:
dateRange
- 日期范围数组separator
- 分隔符,默认为 '~'format
- 日期格式,默认为 'yyyy-MM-dd'
返回值:
string
- 格式化后的日期范围字符串
示例:
typescript
const start = new Date('2023-01-01')
const end = new Date('2023-01-31')
formatDateRange([start, end]) // "2023-01-01 ~ 2023-01-31"
formatDateRange([start, end], ' 至 ') // "2023-01-01 至 2023-01-31"
formatDateRange([start, end], '-', 'MM/dd') // "01/01-01/31"
⏰ 当前时间获取
getCurrentTime
获取当前时间。
typescript
getCurrentTime(pattern: string = 'HH:mm:ss'): string
参数:
pattern
- 格式化模式,默认为 'HH:mm:ss'
返回值:
string
- 格式化后的当前时间字符串
示例:
typescript
getCurrentTime() // "14:30:45"
getCurrentTime('yyyy-MM-dd HH:mm:ss') // "2023-01-15 14:30:45"
getCurrentTime('yyyy年MM月dd日') // "2023年01月15日"
getCurrentDate
获取当前年月日。
typescript
getCurrentDate(): string
返回值:
string
- 当前年月日字符串(yyyy-MM-dd)
示例:
typescript
getCurrentDate() // "2023-01-15"
getCurrentDateTime
获取当前完整日期时间。
typescript
getCurrentDateTime(): string
返回值:
string
- 当前完整日期时间字符串(yyyy-MM-dd HH:mm:ss)
示例:
typescript
getCurrentDateTime() // "2023-01-15 14:30:45"
🔍 日期解析
parseDate
解析日期字符串为Date对象。
typescript
parseDate(dateStr: string): Date | null
参数:
dateStr
- 日期字符串
返回值:
Date | null
- Date对象,解析失败返回null
示例:
typescript
parseDate('2023-01-15') // Date对象
parseDate('2023-01-15 14:30:45') // Date对象
parseDate('invalid date') // null
📅 日期范围获取
getTimeStamp
获取时间戳。
typescript
getTimeStamp(type: 'ms' | 's' = 'ms'): number
参数:
type
- 时间戳类型,'ms'(毫秒)或 's'(秒)
返回值:
number
- 当前时间的时间戳
示例:
typescript
getTimeStamp() // 1673766645123 (毫秒)
getTimeStamp('s') // 1673766645 (秒)
getDateRange
获取日期范围。
typescript
getDateRange(days: number): [Date, Date]
参数:
days
- 天数,负数表示过去,正数表示未来
返回值:
[Date, Date]
- [开始日期, 结束日期]
示例:
typescript
// 获取过去7天的日期范围
getDateRange(-7) // [7天前的日期, 今天]
// 获取未来7天的日期范围
getDateRange(7) // [7天后的日期, 今天]
getCurrentWeekRange
获取本周的开始和结束日期。
typescript
getCurrentWeekRange(): [Date, Date]
返回值:
[Date, Date]
- [周一日期, 周日日期]
示例:
typescript
const [monday, sunday] = getCurrentWeekRange()
console.log(formatDay(monday)) // "2023-01-09" (本周一)
console.log(formatDay(sunday)) // "2023-01-15" (本周日)
getCurrentMonthRange
获取本月的开始和结束日期。
typescript
getCurrentMonthRange(): [Date, Date]
返回值:
[Date, Date]
- [本月第一天, 本月最后一天]
示例:
typescript
const [firstDay, lastDay] = getCurrentMonthRange()
console.log(formatDay(firstDay)) // "2023-01-01"
console.log(formatDay(lastDay)) // "2023-01-31"
addDateRange
添加日期范围到参数对象中,常用于API请求参数构建。
typescript
addDateRange(params: any, dateRange: any[], propName?: string): any
参数:
params
- 参数对象dateRange
- 日期范围数组propName
- 属性名称(可选)
返回值:
any
- 添加了日期范围的参数对象
示例:
typescript
const params = { name: 'test' }
const dateRange = ['2023-01-01', '2023-01-31']
// 使用默认属性名
const result = addDateRange(params, dateRange)
// 结果:{ name: 'test', params: { beginTime: '2023-01-01', endTime: '2023-01-31' } }
// 使用自定义属性名
const result2 = addDateRange(params, dateRange, 'create')
// 结果:{ name: 'test', params: { beginCreate: '2023-01-01', endCreate: '2023-01-31' } }
// 日期范围无效时自动清理
const result3 = addDateRange(params, [])
// 结果:{ name: 'test', params: {} }
🧮 日期计算
getDaysBetween
计算两个日期之间的天数。
typescript
getDaysBetween(start: Date, end: Date): number
参数:
start
- 开始日期end
- 结束日期
返回值:
number
- 天数(绝对值)
示例:
typescript
const start = new Date('2023-01-01')
const end = new Date('2023-01-15')
getDaysBetween(start, end) // 14
getDaysBetween(end, start) // 14 (返回绝对值)
isSameDay
判断是否为同一天。
typescript
isSameDay(date1: Date, date2: Date): boolean
参数:
date1
- 日期1date2
- 日期2
返回值:
boolean
- 是否为同一天
示例:
typescript
const date1 = new Date('2023-01-15 10:00:00')
const date2 = new Date('2023-01-15 20:00:00')
const date3 = new Date('2023-01-16 10:00:00')
isSameDay(date1, date2) // true
isSameDay(date1, date3) // false
getWeekOfYear
获取日期是一年中的第几周。
typescript
getWeekOfYear(date: Date): number
参数:
date
- 日期
返回值:
number
- 周数
示例:
typescript
getWeekOfYear(new Date('2023-01-15')) // 3 (第3周)
getWeekOfYear(new Date('2023-12-31')) // 53 (第53周)
dateAdd
日期加减操作。
typescript
dateAdd(date: Date, type: 'day' | 'month' | 'year', value: number): Date
参数:
date
- 基准日期type
- 类型:'day'、'month'、'year'value
- 增量值,可为负数
返回值:
Date
- 计算后的新日期
示例:
typescript
const baseDate = new Date('2023-01-15')
// 加减天数
dateAdd(baseDate, 'day', 7) // 2023-01-22
dateAdd(baseDate, 'day', -7) // 2023-01-08
// 加减月份
dateAdd(baseDate, 'month', 1) // 2023-02-15
dateAdd(baseDate, 'month', -1) // 2022-12-15
// 加减年份
dateAdd(baseDate, 'year', 1) // 2024-01-15
dateAdd(baseDate, 'year', -1) // 2022-01-15
💡 使用技巧
1. 智能时间戳处理
formatDate
能够自动识别10位和13位时间戳:
typescript
formatDate('1673766645') // 10位时间戳(秒)
formatDate(1673766645000) // 13位时间戳(毫秒)
formatDate('1673766645000') // 字符串形式的毫秒时间戳
2. 灵活的格式化模式
支持多种日期格式,适应不同的业务需求:
typescript
const date = new Date('2023-01-15 14:30:45')
// 中文格式
formatDate(date, 'yyyy年MM月dd日 HH时mm分ss秒')
// 欧洲格式
formatDate(date, 'dd/MM/yyyy')
// 美国格式
formatDate(date, 'MM/dd/yyyy')
// 简短格式
formatDate(date, 'MM-dd HH:mm')
3. API参数构建
结合 addDateRange
简化API请求参数:
typescript
// 构建查询参数
const queryParams = {
page: 1,
size: 10,
keyword: 'test'
}
// 添加时间范围
const [startDate, endDate] = getCurrentMonthRange()
const finalParams = addDateRange(queryParams, [
formatDay(startDate),
formatDay(endDate)
], 'order')
// 发送请求
api.getOrders(finalParams)
// 实际参数:{ page: 1, size: 10, keyword: 'test', params: { beginOrder: '2023-01-01', endOrder: '2023-01-31' } }
4. 表格数据格式化
在表格中统一处理时间显示:
typescript
// Vue表格配置
const columns = [
{
prop: 'createTime',
label: '创建时间',
formatter: (row) => formatTableDate(row.createTime, 'yyyy-MM-dd HH:mm')
},
{
prop: 'updateTime',
label: '更新时间',
formatter: (row) => formatTableDate(row.updateTime, 'MM-dd HH:mm')
}
]
5. 相对时间显示
在消息列表、评论等场景使用相对时间:
typescript
// 消息列表组件
const formatMessageTime = (timestamp) => {
const timeInSeconds = Math.floor(timestamp / 1000)
return formatRelativeTime(timeInSeconds)
}
// 显示效果:
// "刚刚"、"5分钟前"、"2小时前"、"1天前"、"3月15日10时30分"
⚠️ 注意事项
- 时间戳格式:函数会自动判断10位(秒)和13位(毫秒)时间戳
- 时区处理:所有操作基于本地时区,跨时区应用需要额外处理
- 日期有效性:输入无效日期时可能返回
"Invalid Date"
- 性能考虑:频繁的日期格式化可能影响性能,考虑缓存结果
- 兼容性:某些格式化模式在不同浏览器中可能表现不同