mirror of https://github.com/allinssl/allinssl
199 lines
4.5 KiB
Markdown
199 lines
4.5 KiB
Markdown
# 日期处理工具函数文档
|
||
|
||
这个模块提供了一系列用于日期处理的实用工具函数。该模块使用 Ramda.js 进行函数式编程，并提供了完整的 TypeScript 类型支持。
|
||
|
||
## 目录
|
||
|
||
1. [日期格式化](#日期格式化)
|
||
2. [日期计算](#日期计算)
|
||
3. [日期判断](#日期判断)
|
||
4. [时间获取](#时间获取)
|
||
|
||
## 日期格式化
|
||
|
||
### 日期格式化
|
||
|
||
```typescript
|
||
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）
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
formatDate(new Date(), 'YYYY-MM-DD') // 返回: '2024-02-27'
|
||
formatDate('2024-02-27 14:30:00', 'MM/DD HH:mm') // 返回: '02/27 14:30'
|
||
```
|
||
|
||
### 相对时间格式化
|
||
|
||
```typescript
|
||
formatRelativeTime(date: string | number | Date): string
|
||
```
|
||
|
||
将日期转换为相对时间描述。
|
||
|
||
返回格式：
|
||
|
||
- 1分钟内：'刚刚'
|
||
- 1小时内：'x分钟前'
|
||
- 24小时内：'x小时前'
|
||
- 30天内：'x天前'
|
||
- 超过30天：显示具体日期（YYYY-MM-DD）
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
formatRelativeTime(new Date()) // 返回: '刚刚'
|
||
formatRelativeTime(Date.now() - 3600000) // 返回: '1小时前'
|
||
```
|
||
|
||
## 日期计算
|
||
|
||
### 天数差计算
|
||
|
||
```typescript
|
||
getDaysDiff(startDate: string | number | Date, endDate: string | number | Date): number
|
||
getDaysDiffCurried(startDate: string | number | Date)(endDate: string | number | Date): number
|
||
```
|
||
|
||
计算两个日期之间的天数差。提供普通版本和柯里化版本。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
getDaysDiff('2024-02-01', '2024-02-27') // 返回: 26
|
||
const diffFromToday = getDaysDiffCurried(new Date())
|
||
diffFromToday('2024-03-27') // 返回: 30
|
||
```
|
||
|
||
### 添加天数
|
||
|
||
```typescript
|
||
addDays(days: number, date: string | number | Date): Date
|
||
addDaysCurried(days: number)(date: string | number | Date): Date
|
||
```
|
||
|
||
在指定日期上添加或减少天数。提供普通版本和柯里化版本。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
addDays(7, new Date()) // 返回: 7天后的日期
|
||
addDays(-7, new Date()) // 返回: 7天前的日期
|
||
```
|
||
|
||
## 日期判断
|
||
|
||
### 日期范围判断
|
||
|
||
```typescript
|
||
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
|
||
```
|
||
|
||
判断日期是否在指定范围内。提供普通版本和柯里化版本。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
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
|
||
```
|
||
|
||
## 时间获取
|
||
|
||
### 获取一天的开始时间
|
||
|
||
```typescript
|
||
getStartOfDay(date: string | number | Date): Date
|
||
```
|
||
|
||
获取指定日期的开始时间（00:00:00）。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
getStartOfDay('2024-02-27 15:30:00') // 返回: 2024-02-27 00:00:00
|
||
```
|
||
|
||
### 获取一天的结束时间
|
||
|
||
```typescript
|
||
getEndOfDay(date: string | number | Date): Date
|
||
```
|
||
|
||
获取指定日期的结束时间（23:59:59.999）。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
getEndOfDay('2024-02-27 15:30:00') // 返回: 2024-02-27 23:59:59.999
|
||
```
|
||
|
||
### 获取星期几
|
||
|
||
```typescript
|
||
getDayOfWeek(date: string | number | Date): string
|
||
```
|
||
|
||
获取指定日期是星期几。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
getDayOfWeek('2024-02-27') // 返回: '星期二'
|
||
```
|
||
|
||
### 获取到期时间
|
||
|
||
```typescript
|
||
getDaysUntilExpiration(date: string | number | Date, expirationDate?: string | number | Date): string
|
||
```
|
||
|
||
获取距离到期时间的天数。
|
||
|
||
参数：
|
||
|
||
- `date`: 目标日期
|
||
- `expirationDate`: 到期日期，默认为当前时间
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
getDaysUntilExpiration('2024-03-27') // 返回: '30天'
|
||
getDaysUntilExpiration('2024-01-27') // 返回: '已过期'
|
||
```
|
||
|
||
## 特点
|
||
|
||
1. 使用 TypeScript 编写，提供完整的类型支持
|
||
2. 使用 Ramda.js 进行函数式编程
|
||
3. 提供多个函数的柯里化版本
|
||
4. 支持多种日期输入格式
|
||
5. 丰富的日期处理功能
|
||
|
||
## 注意事项
|
||
|
||
1. 所有接收日期的函数都支持字符串、时间戳和 Date 对象作为输入
|
||
2. 日期格式化函数会自动补零，确保输出格式统一
|
||
3. 天数差计算会忽略时分秒，只计算日期差
|
||
4. 范围判断包含起始和结束日期
|
||
5. 使用柯里化函数时注意参数顺序
|