allinssl/frontend/packages/utils/docs/date.md

日期处理工具函数文档

这个模块提供了一系列用于日期处理的实用工具函数。该模块使用 Ramda.js 进行函数式编程，并提供了完整的 TypeScript 类型支持。

目录

1. 日期格式化
2. 日期计算
3. 日期判断
4. 时间获取

日期格式化

日期格式化

formatDate(date: string | number | Date, format: string = 'YYYY-MM-DD HH:mm:ss'): string

将日期转换为指定格式的字符串。

参数：

• date: 日期字符串、时间戳或 Date 对象
• format: 格式化字符串，默认为 'YYYY-MM-DD HH:mm:ss'

支持的格式化占位符：

• YYYY: 年份
• MM: 月份（01-12）
• DD: 日期（01-31）
• HH: 小时（00-23）
• mm: 分钟（00-59）
• ss: 秒钟（00-59）

示例：

formatDate(new Date(), 'YYYY-MM-DD') // 返回: '2024-02-27'
formatDate('2024-02-27 14:30:00', 'MM/DD HH:mm') // 返回: '02/27 14:30'

相对时间格式化

formatRelativeTime(date: string | number | Date): string

将日期转换为相对时间描述。

返回格式：

• 1分钟内：'刚刚'
• 1小时内：'x分钟前'
• 24小时内：'x小时前'
• 30天内：'x天前'
• 超过30天：显示具体日期（YYYY-MM-DD）

示例：

formatRelativeTime(new Date()) // 返回: '刚刚'
formatRelativeTime(Date.now() - 3600000) // 返回: '1小时前'

日期计算

天数差计算

getDaysDiff(startDate: string | number | Date, endDate: string | number | Date): number
getDaysDiffCurried(startDate: string | number | Date)(endDate: string | number | Date): number

计算两个日期之间的天数差。提供普通版本和柯里化版本。

示例：

getDaysDiff('2024-02-01', '2024-02-27') // 返回: 26
const diffFromToday = getDaysDiffCurried(new Date())
diffFromToday('2024-03-27') // 返回: 30

添加天数

addDays(days: number, date: string | number | Date): Date
addDaysCurried(days: number)(date: string | number | Date): Date

在指定日期上添加或减少天数。提供普通版本和柯里化版本。

示例：

addDays(7, new Date()) // 返回: 7天后的日期
addDays(-7, new Date()) // 返回: 7天前的日期

日期判断

日期范围判断

isDateInRange(date: string | number | Date, startDate: string | number | Date, endDate: string | number | Date): boolean
isDateInRangeCurried(date: string | number | Date)(startDate: string | number | Date)(endDate: string | number | Date): boolean

判断日期是否在指定范围内。提供普通版本和柯里化版本。

示例：

isDateInRange('2024-02-27', '2024-02-01', '2024-03-01') // 返回: true
const checkDateRange = isDateInRangeCurried('2024-02-27')
checkDateRange('2024-02-01')('2024-03-01') // 返回: true

时间获取

获取一天的开始时间

getStartOfDay(date: string | number | Date): Date

获取指定日期的开始时间（00:00:00）。

示例：

getStartOfDay('2024-02-27 15:30:00') // 返回: 2024-02-27 00:00:00

获取一天的结束时间

getEndOfDay(date: string | number | Date): Date

获取指定日期的结束时间（23:59:59.999）。

示例：

getEndOfDay('2024-02-27 15:30:00') // 返回: 2024-02-27 23:59:59.999

获取星期几

getDayOfWeek(date: string | number | Date): string

获取指定日期是星期几。

示例：

getDayOfWeek('2024-02-27') // 返回: '星期二'

获取到期时间

getDaysUntilExpiration(date: string | number | Date, expirationDate?: string | number | Date): string

获取距离到期时间的天数。

参数：

• date: 目标日期
• expirationDate: 到期日期，默认为当前时间

示例：

getDaysUntilExpiration('2024-03-27') // 返回: '30天'
getDaysUntilExpiration('2024-01-27') // 返回: '已过期'

特点

1. 使用 TypeScript 编写，提供完整的类型支持
2. 使用 Ramda.js 进行函数式编程
3. 提供多个函数的柯里化版本
4. 支持多种日期输入格式
5. 丰富的日期处理功能

注意事项

1. 所有接收日期的函数都支持字符串、时间戳和 Date 对象作为输入
2. 日期格式化函数会自动补零，确保输出格式统一
3. 天数差计算会忽略时分秒，只计算日期差
4. 范围判断包含起始和结束日期
5. 使用柯里化函数时注意参数顺序