# date

日期处理工具函数 / Date handling utilities

基于 dayjs / Based on dayjs

## Overview / 概述

提供一系列日期处理函数，包括日期格式化、相对时间显示、时长格式化等。所有函数基于 [dayjs](https://dayjs.gitee.io/) 库。

Provide a series of date handling functions including date formatting, relative time display, duration formatting, etc. All functions are based on [dayjs](https://dayjs.gitee.io/).

## Functions

### useDate

使用 dayjs 实例 / Get dayjs instance

```ts
function useDate(date?: ConfigType, format?: OptionType, strict?: boolean): Dayjs
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `ConfigType` | `undefined` | 日期值，支持时间戳、Date 对象、字符串 |
| `format` | `OptionType` | `undefined` | 日期格式 |
| `strict` | `boolean` | `false` | 是否严格模式 |

**Returns / 返回值**

- `Dayjs`: dayjs 实例

**Example / 示例**

```ts
// 默认当前时间
useDate().format('YYYY-MM-DD HH:mm:ss')
// '2024-03-02 15:30:00'

// 时间戳
useDate(1709286300000).format('YYYY-MM-DD')
// '2024-03-02'

// 字符串日期
useDate('2024-03-02').format('YYYY-MM-DD')
// '2024-03-02'

// Date 对象
useDate(new Date()).format('YYYY-MM-DD')
```

---

### dateFormat

日期转格式字符串 / Format date to string

```ts
function dateFormat(date: ConfigType, fmt?: string): string
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `ConfigType` | - | 日期值 |
| `fmt` | `string` | `'YYYY-MM-DD HH:mm:ss'` | 格式化字符串 |

**Format Tokens / 格式化占位符**

| Token | Description | Example |
|-------|-------------|---------|
| `YYYY` | 4位年份 | 2024 |
| `YY` | 2位年份 | 24 |
| `MM` | 2位月份 | 03 |
| `M` | 1-2位月份 | 3 |
| `DD` | 2位日期 | 02 |
| `D` | 1-2位日期 | 2 |
| `HH` | 24小时制 | 15 |
| `hh` | 12小时制 | 03 |
| `mm` | 分钟 | 30 |
| `ss` | 秒数 | 45 |

**Example / 示例**

```ts
// 完整日期时间
dateFormat(1709286300000, 'YYYY-MM-DD HH:mm:ss')
// '2024-03-02 15:30:00'

// 仅日期
dateFormat(new Date(), 'YYYY-MM-DD')
// '2024-03-02'

// 中文格式
dateFormat(new Date(), 'YYYY年MM月DD日')
// '2024年03月02日'

// 时间
dateFormat(new Date(), 'HH:mm:ss')
// '15:30:45'
```

---

### minute

返回当前时间（默认到分钟）/ Get current time (default to minute)

```ts
function minute(date?: ConfigType, fmt?: string): string
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `ConfigType` | `undefined` | 日期值 |
| `fmt` | `string` | `'YYYY-MM-DD HH:mm'` | 格式化字符串 |

**Example / 示例**

```ts
minute()
// '2024-03-02 15:30'

minute(new Date(), 'YYYY-MM-DD HH:mm:ss')
// '2024-03-02 15:30:45'
```

---

### dateMonthDays

返回日期对应月份天数 / Get days in month

```ts
function dateMonthDays(date?: ConfigType): number
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `ConfigType` | `undefined` | 日期值，默认当前月份 |

**Example / 示例**

```ts
dateMonthDays('2024-02-01')  // 29 (2024年是闰年)
dateMonthDays('2023-02-01')  // 28
dateMonthDays('2024-04-01')  // 30
```

---

### getCurrDate

返回前后 i 天的日期字符串 / Get date before/after i days

```ts
function getCurrDate(i?: number, format?: string): string
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `i` | `number` | `0` | 天数偏移量，正数为未来，负数为过去 |
| `format` | `string` | `'YYYY-MM-DD'` | 格式化字符串 |

**Example / 示例**

```ts
// 今天
getCurrDate()
// '2024-03-02'

// 明天
getCurrDate(1)
// '2024-03-03'

// 前天
getCurrDate(-1)
// '2024-03-01'

// 一周后
getCurrDate(7)
// '2024-03-09'

// 自定义格式
getCurrDate(1, 'YYYY/MM/DD')
// '2024/03/03'
```

---

### dateDiff

返回两个日期时间差 / Get date difference

```ts
function dateDiff(date1: ConfigType, date2?: ConfigType, unit?: QUnitType | OpUnitType): number
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `date1` | `ConfigType` | - | 第一个日期 |
| `date2` | `ConfigType` | `undefined` | 第二个日期，默认当前时间 |
| `unit` | `QUnitType \| OpUnitType` | `undefined` | 返回单位 |

**Unit Options / 单位选项**

| Unit | Description |
|------|-------------|
| `ms` / `millisecond` | 毫秒 |
| `s` / `second` | 秒 |
| `m` / `minute` | 分钟 |
| `h` / `hour` | 小时 |
| `d` / `day` | 天 |
| `M` / `month` | 月 |
| `y` / `year` | 年 |

**Example / 示例**

```ts
// 相差天数
dateDiff('2024-03-02', '2024-03-01')
// 1

// 相差小时
dateDiff('2024-03-02 15:00', '2024-03-02 10:00', 'hour')
// 5

// 相差分钟
dateDiff('2024-03-02 15:30:00', '2024-03-02 15:00:00', 'minute')
// 30

// 相对于当前时间
dateDiff('2024-03-01')
// -1 (昨天)
// 或正数如果是未来
```

---

### dateFromNow

相对时间显示 / Relative time display

```ts
function dateFromNow(date: ConfigType, format?: Format): string
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `ConfigType` | - | 目标日期 |
| `format` | `Format` | `undefined` | 自定义格式 |

**Default Format / 默认格式**

```ts
{
  zero: '刚刚',
  minuteAgo: '${m}分钟前',
  today: '今天 ${HH:mm}',
  yesterday: '昨天 ${HH:mm}',
  other: '${YYYY/MM/DD}',
  future: '${YYYY/MM/DD}'
}
```

**Example / 示例**

```ts
// 几分钟前
dateFromNow('2024-03-02 15:25:00')
// '5分钟前' (假设当前15:30)

// 今天内
dateFromNow('2024-03-02 10:00:00')
// '今天 10:00'

// 昨天
dateFromNow('2024-03-01 10:00:00')
// '昨天 10:00'

// 更早
dateFromNow('2024-02-15 10:00:00')
// '2024/02/15'

// 自定义格式
dateFromNow('2024-03-02 10:00:00', {
  today: '今日 ${HH:mm}',
  yesterday: '昨日 ${HH:mm}'
})
// '今日 10:00'
```

---

### dateDiffFormat

计算两个日期之间的差值（自然年月日）/ Date difference in natural units

```ts
function dateDiffFormat(startDate: string | number | Date, endDate?: string | number | Date, format?: string): string
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `startDate` | `string \| number \| Date` | - | 起始日期 |
| `endDate` | `string \| number \| Date` | `undefined` | 结束日期，默认当前时间 |
| `format` | `string` | `'YY年MM个月DD天'` | 输出格式 |

**Format Tokens / 格式化占位符**

| Token | Description |
|-------|-------------|
| `YY` | 年 |
| `MM` | 月 |
| `DD` | 天 |
| `HH` | 小时 |
| `mm` | 分钟 |
| `ss` | 秒 |

**Example / 示例**

```ts
dateDiffFormat('2024-01-01', '2024-03-15')
// '2月14天'

dateDiffFormat('2024-01-01', '2024-03-15', 'YY年MM个月DD天')
// '0年2个月14天'

dateDiffFormat('2024-01-01 10:00', '2024-01-01 10:30', 'HH:mm')
// '00:30'

dateDiffFormat('2024-01-01', '2025-06-15', 'YY年MM个月DD天')
// '1年5个月14天'
```

---

### durationFormat

格式化时长 / Format duration

```ts
function durationFormat(duration: string | number, config?: { unit?: DurationUnitType; format?: string | string[] }): string | string[]
```

**Parameters / 参数**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `duration` | `string \| number` | - | 时长数值 |
| `config.unit` | `DurationUnitType` | `'ms'` | 输入数值的单位 |
| `config.format` | `string \| string[]` | `'HH小时mm分钟'` | 输出格式 |

**Unit Options / 单位选项**

| Unit | Description |
|------|-------------|
| `d` / `D` | 天 |
| `h` / `H` | 小时 |
| `m` | 分钟 |
| `s` | 秒 |
| `ms` | 毫秒 |

**Example / 示例**

```ts
// 毫秒转小时分钟
durationFormat(3661000, { unit: 'ms' })
// '1小时1分钟'

// 指定格式
durationFormat(61, { unit: 'm', format: 'HH:mm' })
// '01:01'

// 返回数组
durationFormat(61, { unit: 'm', format: ['H', 'm'] })
// ['1', '1']

// 秒转时分秒
durationFormat(3665, { unit: 's', format: 'HH:mm:ss' })
// '01:01:05'
```

---

### durationFormatNoZero

格式化时长（去掉 0）/ Format duration without zero

```ts
function durationFormatNoZero(duration: string | number, config?: { unit?: DurationUnitType; format?: string }): string | string[]
```

**Example / 示例**

```ts
// 去掉为0的单位
durationFormatNoZero(61, { unit: 'm' })
// '1小时1分钟'

// 长时间只显示天数
durationFormatNoZero(3600000, { unit: 'ms', format: 'D天H小时m分钟' })
// '1天'

// 整天不带0
durationFormatNoZero(86400000, { unit: 'ms', format: 'D天H小时m分钟' })
// '1天'
```

---

## Use Cases / 使用场景

### 消息列表时间显示 / Message List Time Display

```ts
function formatMessageTime(date: string | Date) {
  return dateFromNow(date)
}
```

### 订单耗时显示 / Order Duration Display

```ts
function formatOrderDuration(startTime: number) {
  const duration = Date.now() - startTime
  return durationFormat(duration, { unit: 'ms', format: 'DD天HH小时mm分钟' })
}
```

### 会员有效期 / Membership Validity

```ts
function getMembershipExpiry(startDate: string, months: number) {
  const expiryDate = useDate(startDate).add(months, 'month')
  return dateFormat(expiryDate, 'YYYY-MM-DD')
}
```

### 聊天时间分割线 / Chat Time Divider

```ts
function shouldShowDateDivider(messages: Message[]) {
  return messages.map((msg, index) => {
    if (index === 0) return true
    const prevDate = useDate(messages[index - 1].createdAt)
    const currDate = useDate(msg.createdAt)
    return !currDate.isSame(prevDate, 'day')
  })
}
```