# informat.date 日期操作

## 概述

使用`informat.date`对象进行日期相关操作

## format

格式化日期

```javascript
informat.date.format(date, format)
```

| 参数     | 类型    | 描述     |
|--------|-------|--------|
| date   | `Date`  | 日期对象   |
| format | `String` | 格式化表达式 |

**返回值**

类型为`String`，格式化后的字符串

**示例**

::: code-group

```javascript [调用]
informat.date.format(new Date(), 'yyyy-MM-dd HH:mm:ss')
```
```text [返回值]
2023-05-09 11:04:48
```
:::

## parse

从字符串解析日期

```javascript
informat.date.parse(str, format)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| str    | `String` | 日期字符串  |
| format | `String` | 格式化表达式 |

**返回值**

类型为`Date`，如果解析失败返回`null`

**示例**

::: code-group

```javascript [调用]
informat.date.parse('2023-05-09 11:04:48', 'yyyy-MM-dd HH:mm:ss')
```
```text [返回值]
Tue May 09 11:04:48 CST 2023
```
:::


## parseDate

从字符串解析日期

```javascript
informat.date.parseDate(str)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| str    | `String` | 日期字符串  |

**返回值**

类型为`Date`，如果解析失败返回`null`

**示例**

::: code-group

```javascript [调用]
informat.date.parseDate('2023-05-09 11:04:48')
informat.date.parseDate('2023-05-09 11:04')
informat.date.parseDate('2023-05-09 11')
informat.date.parseDate('2023-05-09')
informat.date.parseDate('2018-10-26T07:01:26Z')
informat.date.parseDate('1741337150957')

```
```text [返回值]
Tue May 09 11:04:48 CST 2023 
Tue May 09 11:04:00 CST 2023 
Tue May 09 00:00:00 CST 2023 
Tue May 09 00:00:00 CST 2023 
Fri Oct 26 15:01:26 CST 2018 
Fri Mar 07 16:45:50 CST 2025
```
:::


## dateToTimestamp

日期类型转换为距离UNIX时间戳数字值

```javascript
informat.date.dateToTimestamp(date)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| date   | Date   | 日期对象   |

**返回值**

类型 `Integer`
转换后的UNIX时间戳，如果date为`null`则返回`null`

**示例**

::: code-group

```javascript [调用]
informat.date.dateToTimestamp(new Date())
```
```text [返回值]
1667232000000
```
:::


## timestampToDate

UNIX时间戳数字值转换为日期类型

```javascript
informat.date.timestampToDate(date)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| timestamp   | Integer   | UNIX时间戳   |

**返回值**

类型 `Date`
转换后的日期,如果timestamp为`null`返回`null`

**示例**

::: code-group

```javascript [调用]
informat.date.timestampToDate(1667232000000)
```
```text [返回值]
Tue Nov 01 00:00:00 CST 2022
```
:::


## getDateOfThisWeek

获取本周几对应的日期

```javascript
informat.date.getDateOfThisWeek(dayOfWeek)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| dayOfWeek   | int   | 周几，值为1-7之间的数字   |

**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getDateOfThisWeek(7)
```
```text [返回值]
Tue Apr 06 00:00:00 CST 2025 
```
:::

## getMonday

获取当前日期所在周的周一0点（小时、分钟、秒数、毫秒数都是0）

```javascript
informat.date.getMonday()
```


**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getMonday()
```
```text [返回值]
Mon Apr 21 00:00:00 CST 2025
```
:::



## getMonday

获取date日期所在周的周一0点（小时、分钟、秒数、毫秒数都是0）

```javascript
informat.date.getMonday(date)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| date   | Date   | 日期对象   |


**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getMonday(new Date())
```
```text [返回值]
Mon Apr 14 00:00:00 CST 2025
```
:::



## getStartOfDay

获取当前日期的0点0分0秒

```javascript
informat.date.getStartOfDay()
```


**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getStartOfDay()
```
```text [返回值]
Tue Apr 06 00:00:00 CST 2025 
```
:::


## getStartOfDay

获取指定日期的0点0分0秒

```javascript
informat.date.getStartOfDay(date)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| date   | Date   | 日期对象   |

**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getStartOfDay(new Date())
```
```text [返回值]
Tue Apr 06 00:00:00 CST 2025 
```
:::



## getStartOfMonth

获取当前日期所在月的1号，如5月1号0点（小时、分钟、秒数、毫秒数都是0）

```javascript
informat.date.getStartOfMonth()
```


**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getStartOfMonth()
```
```text [返回值]
Tue Apr 01 00:00:00 CST 2025 
```
:::


## getStartOfMonth

获取date日期所在月的1号，如果5月1号0点（小时、分钟、秒数、毫秒数都是0）

```javascript
informat.date.getStartOfMonth(date)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| date   | Date   | 日期对象   |

**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getStartOfMonth(new Date())
```
```text [返回值]
Tue Apr 01 00:00:00 CST 2025 
```
:::



## getStartOfYear

获取当前日期所在年的元旦，如2025年1月1号0点（小时、分钟、秒数、毫秒数都是0）

```javascript
informat.date.getStartOfYear()
```


**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getStartOfYear()
```
```text [返回值]
Wed Jan 01 00:00:00 CST 2025 
```
:::


## getStartOfYear

获取date日期所在年的元旦，如2025年1月1号0点（小时、分钟、秒数、毫秒数都是0）

```javascript
informat.date.getStartOfYear(date)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| date   | Date   | 日期对象   |

**返回值**

类型 `Date`

**示例**

::: code-group

```javascript [调用]
informat.date.getStartOfYear(new Date())
```
```text [返回值]
Wed Jan 01 00:00:00 CST 2025 
```
:::


## isSameDay

判断是否是同一天

```javascript
informat.date.isSameDay(date1, date2)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| date1   | Date   | 日期对象1   |
| date2   | Date   | 日期对象2   |

**返回值**

类型 `Boolean`

**示例**

::: code-group

```javascript [调用]
informat.date.isSameDay(date1, date2)
```
```text [返回值]
true
```
:::

## dateAdd

日期偏移

```javascript
informat.date.dateAdd(d, type, value)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| d    | Date或Long | 需要计算的日期或UNIX时间戳                           |
| type   | String   | 偏移单位  |
| diff | Integer   | 增加或者减少的值,如果为 null 则默认0 开始。增加则传递整数，减少则传递负数 |


::: info
type的取值为：`年:year`,`月:month`,`天:day_of_year`,`月天数:day_of_month`,`周天数:day_of_week`,`小时:hour`,`分钟:minute`,`秒:second`,`毫秒:millisecond`
:::

**返回值**

类型 `Date`

**示例**

```javascript
//假设date的值为2022-11-01 00:00:00,000，时间戳 timestamp 为 1667232000000
informat.date.dateAdd(date, 'year', 1); //2023-11-01 00:00:00,000
informat.date.dateAdd(date, 'year', null); //2022-11-01 00:00:00,000
informat.date.dateAdd(date, 'year', -1); //2021-11-01 00:00:00,000
informat.date.dateAdd(date, 'month', 1); //2022-12-01 00:00:00,000
informat.date.dateAdd(date, 'day_of_year', 1); //2022-11-02 00:00:00,000
informat.date.dateAdd(date, 'day_of_month', 1); //2022-11-02 00:00:00,000
informat.date.dateAdd(date, 'day_of_week', 1); //2022-11-02 00:00:00,000
informat.date.dateAdd(date, 'hour', 1); //2022-11-01 01:00:00,000
informat.date.dateAdd(date, 'minute', 1); //2022-11-01 00:01:00,000
informat.date.dateAdd(date, 'second', 1); //2022-11-01 00:00:01,000
informat.date.dateAdd(date, 'millisecond', 1); //2022-11-01 00:00:00,001
informat.date.dateAdd(timestamp, 'year', 2); //2024-11-01 00:00:00,000
informat.date.dateAdd(timestamp, 'month', 1); //2022-12-01 00:00:00,000
```

## dateBefore

判定日期d1是否在日期d2之前

```javascript
informat.date.dateBefore(d1, d2)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| d1 | `Date`或`Long` | 日期1或UNIX时间戳 |
| d2 | `Date`或`Long`| 日期2或UNIX时间戳 |

**返回值**

类型 `Boolean`
日期d1是否在日期d2之前,如果d1和d2相等返回false

**示例**

```javascript
//假设date1的值为 2022-11-01 13:10:12,000，时间戳 timestamp 为 1667279412000
//假设date2的值为 2022-02-02 13:10:12,000，时间戳 timestamp 为 1643778612000

informat.date.dateBefore(date1, date2); //false
informat.date.dateBefore(date2, date1); //true
informat.date.dateBefore(timestamp1, timestamp2); //false
informat.date.dateBefore(timestamp2, timestamp1); //true
informat.date.dateBefore(timestamp1, date2); //false
informat.date.dateBefore(timestamp2, date1); //true
informat.date.dateBefore(date1, null); //false
informat.date.dateBefore(null, date2); //false
informat.date.dateBefore(timestamp1, null); //false
informat.date.dateBefore(null, timestamp2); //false
informat.date.dateBefore(null, null); //false
```


## datePart

返回日期d中的type指定的部分

```javascript
informat.date.datePart(d, type)
```

| 参数     | 类型     | 描述     |
|--------|--------|--------|
| d    | `Date`或`Long` | 需要计算的日期或UNIX时间戳 |
| type | `String`    | 运算类型   

::: info
- type的取值为：`年:year`,`月:month`,`天:day_of_year`,`月天数:day_of_month`,`周天数:day_of_week`,`小时:hour`,`分钟:minute`,`秒:second`,`毫秒:millisecond`
- ***month***是从0开始，比如date是11月，informat.date.datePart(date, 'month'); 返回为10
:::

**返回值**

类型 `Integer`
日期d中type指定的部分

**示例**

```javascript
//假设date的值为2022-11-01 13:10:12,000，时间戳 timestamp 为 1667279412000
informat.date.datePart(date, 'year'); //2022
informat.date.datePart(date, 'month'); //10
informat.date.datePart(date, 'day_of_year'); //305
informat.date.datePart(date, 'day_of_month'); //1
informat.date.datePart(date, 'day_of_week'); //3
informat.date.datePart(date, 'hour'); //13
informat.date.datePart(date, 'minute'); //10
informat.date.datePart(date, 'second'); //12
informat.date.datePart(date, 'millisecond'); //0
informat.date.datePart(null, 'year'); //null
informat.date.datePart(date, null); //null
informat.date.datePart(timestamp, 'year'); //2022
informat.date.datePart(timestamp, 'month'); //10
informat.date.datePart(date, 'week_of_year'); //45
```
