# Date日期

## 概述

日期运算的。包括有关月份和星期的值范围的信息，以及几种用于处理日期的方法，如`Date.sysdate`，`Date.now` 和 `Date.dateSet`
及有关月份和星期值范围的特殊说明

**特殊说明**

month的值范围

| 月份  | 值  |
|-----|----|
| 1月  | 0  |
| 2月  | 1  |
| 3月  | 2  |
| 4月  | 3  |
| 5月  | 4  |
| 6月  | 5  |
| 7月  | 6  |
| 8月  | 7  |
| 9月  | 8  |
| 10月 | 9  |
| 11月 | 10 |
| 12月 | 11 |

day_of_week的值范围

| 天   | 值   |
| ------ | ---- |
| 星期日 | 0    |
| 星期一 | 1    |
| 星期二 | 2    |
| 星期三 | 3    |
| 星期四 | 4    |
| 星期五 | 5    |
| 星期六 | 6    |


## sysdate

返回当前日期和时间

```javascript
Date.sysdate()
```

**返回值**

类型 `Date`
当前的日期和时间

**示例**

```javascript
Date.sysdate() //Date 对象 
```

## now

返回当前时间的UNIX时间戳

```javascript
Date.now()
```

**返回值**

类型 `Long`
当前时间的UNIX时间戳

**示例**

```javascript
Date.now() // 1668483800328
```

## newDate

返回指定的日期

```javascript
Date.newDate(year, month, day, hour, minute, second, millisecond);
```

| 参数          | 类型        | 描述                              |
|-------------|-----------|---------------------------------|
| year        | `Integer` | 年份,非必填或可以传递为null,默认为**当前时间的年份** |
| month       | `Integer` | 月份,非必填或可以传递为null,默认为**1月**      |
| day         | `Integer` | 天,非必填或可以传递为null,默认为**1**        |
| hour        | `Integer` | 小时,非必填或可以传递为null,默认为**0点**      |
| minute      | `Integer` | 分钟,非必填或可以传递为null,默认为**0分**      |
| second      | `Integer` | 秒,非必填或可以传递为null,默认为**0秒**       |
| millisecond | `Integer` | 毫秒,非必填或可以传递为null,默认为**0毫秒**     |


**返回值**

类型 `Date` 返回指定的日期

**示例**

```javascript
Date.newDate(); //不传递则返回当前日期和时间
Date.newDate(null); //2025-01-01 00:00:00,000
Date.newDate(2022);// 2022-01-01 00:00:00,000
Date.newDate(2025, 0, 3); // 2025-01-03 00:00:00,000
Date.newDate(2025, 0, 1, 2, 3, 4, 5);// 2025-01-01 02:03:04,005
Date.newDate(2025, null, null); // 2025-01-01 00:00:00,000
Date.newDate(null, null, null, null, null, null, null, null); // 2025-01-01 00:00:00,000
Date.newDate(null, 0, 1, 2, 3, 4, 5, 6); // 2025-01-01 02:03:04,005
Date.newDate(null, 0, 1, null, 3, 4, 5); // 2025-01-01 00:03:04,005
```

## dateSet

将日期d中type指定的部分设置为value

```javascript
Date.dateSet(d, type, value)
```

| 参数    | 类型        | 描述                    |
|-------|-----------|-----------------------|
| d     | `Date`或`Long` | 需要计算的日期或UNIX时间戳       |
| type  | `String`    | 运算类型                  |
| value | `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
Date.dateSet(date, 'year', 2024); //2024-11-01 00:00:00,000
Date.dateSet(date, 'year', null); //0001-11-01 00:00:00,000
Date.dateSet(date, 'year', -1); //0002-11-01 00:00:00,000
Date.dateSet(null, 'year', 2024); //null
Date.dateSet(date, null, 2024); //null
Date.dateSet(date, 'month', 1); //2022-02-01 00:00:00,000
Date.dateSet(date, 'day_of_year', 1); //2022-01-01 00:00:00,000
Date.dateSet(date, 'day_of_month', 1); //2022-11-01 00:00:00,000
Date.dateSet(date, 'day_of_week', 1); //2022-10-30 00:00:00,000
Date.dateSet(date, 'hour', 1); //2022-11-01 01:00:00,000
Date.dateSet(date, 'minute', 1); //2022-11-01 00:01:00,000
Date.dateSet(date, 'second', 1); //2022-11-01 00:00:01,000
Date.dateSet(date, 'millisecond', 1); //2022-11-01 00:00:00,001
Date.dateSet(timestamp, 'year', 2024); //2024-11-01 00:00:00,000
Date.dateSet(timestamp, 'month', 1); //2022-02-01 00:00:00,000
```


## dateAdd

计算日期d按照类型type加上diff的日期

```javascript
Date.dateAdd(d, type, diff)
```

| 参数   | 类型        | 描述                                        |
|------|-----------|-------------------------------------------|
| 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
Date.dateAdd(date, 'year', 1); //2023-11-01 00:00:00,000
Date.dateAdd(date, 'year', null); //2022-11-01 00:00:00,000
Date.dateAdd(date, 'year', -1); //2021-11-01 00:00:00,000
Date.dateAdd(date, 'month', 1); //2022-12-01 00:00:00,000
Date.dateAdd(date, 'day_of_year', 1); //2022-11-02 00:00:00,000
Date.dateAdd(date, 'day_of_month', 1); //2022-11-02 00:00:00,000
Date.dateAdd(date, 'day_of_week', 1); //2022-11-02 00:00:00,000
Date.dateAdd(date, 'hour', 1); //2022-11-01 01:00:00,000
Date.dateAdd(date, 'minute', 1); //2022-11-01 00:01:00,000
Date.dateAdd(date, 'second', 1); //2022-11-01 00:00:01,000
Date.dateAdd(date, 'millisecond', 1); //2022-11-01 00:00:00,001
Date.dateAdd(timestamp, 'year', 2); //2024-11-01 00:00:00,000
Date.dateAdd(timestamp, 'month', 1); //2022-12-01 00:00:00,000
```



## datePart

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

```javascript
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`
:::

**返回值**

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

**示例**

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



## dateBefore

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

```javascript
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

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



## dateAfter

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

```javascript
Date.dateAfter(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

Date.dateAfter(date1, date2); //true
Date.dateAfter(date2, date1); //false
Date.dateAfter(timestamp1, timestamp2); //true
Date.dateAfter(timestamp2, timestamp1); //false
Date.dateAfter(timestamp1, date2); //true
Date.dateAfter(timestamp2, date1); //false
Date.dateAfter(date1, null); //false
Date.dateAfter(null, date2); //false
Date.dateAfter(timestamp1, null); //false
Date.dateAfter(null, timestamp2); //false
Date.dateAfter(null, null); //false
```



## dateDiff

计算两个日期之间的天数差值

```javascript
Date.dateDiff(d1, d2)
```

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

**返回值**

类型 `Integer`
计算两个日志之间相差的天数。相等则会0，若d1在d2之前，则返回负值，反之返回正值

**示例**

```javascript
//假设date1的值为 2022-10-01 13:10:12，时间戳 timestamp 为 1667279412000
//假设date2的值为 2023-12-01 13:10:12，时间戳 timestamp 为 1701407412000

Date.dateDiff(date1, date2); //-426
Date.dateDiff(date2, date1); //426
Date.dateDiff(timestamp1, timestamp2); //-426
Date.dateDiff(timestamp2, timestamp1); //426
Date.dateDiff(timestamp1, date2); //-426
Date.dateDiff(timestamp2, date1); //426
Date.dateDiff(date1, null); //null
Date.dateDiff(null, date2); //null
Date.dateDiff(timestamp1, null); //null
Date.dateDiff(null, timestamp2); //null
Date.dateDiff(null, null); //null
```



## monthDiff

计算两个日期之间的月份数差值

```javascript
Date.monthDiff(d1, d2)
```

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

**返回值**

类型 `Integer`
计算两个日志之间相差的月份数。相等则会0，若d1在d2之前，则返回负值，反之返回正值

**示例**

```javascript
//假设date1的值为 2022-10-01 13:10:12，时间戳 timestamp 为 1667279412000
//假设date2的值为 2023-12-01 13:10:12，时间戳 timestamp 为 1701407412000

Date.monthDiff(date1, date2); //-14
Date.monthDiff(date2, date1); //14
Date.monthDiff(timestamp1, timestamp2); //-14
Date.monthDiff(timestamp2, timestamp1); //14
Date.monthDiff(timestamp1, date2); //-14
Date.monthDiff(timestamp2, date1); //14
Date.monthDiff(date1, null); //null
Date.monthDiff(null, date2); //null
Date.monthDiff(timestamp1, null); //null
Date.monthDiff(null, timestamp2); //null
Date.monthDiff(null, null); //null
```



## weekDiff

计算两个日期之间的周差值

```javascript
Date.weekDiff(d1, d2)
```

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

**返回值**

类型 `Integer`
计算两个日志之间相差的周数。相等则会0，若d1在d2之前，则返回负值，反之返回正值

**示例**

```javascript
//假设date1的值为 2022-10-01 13:10:12，时间戳 timestamp 为 1667279412000
//假设date2的值为 2023-12-01 13:10:12，时间戳 timestamp 为 1701407412000

Date.weekDiff(date1, date2); //-60
Date.weekDiff(date2, date1); //60
Date.weekDiff(timestamp1, timestamp2); //-60
Date.weekDiff(timestamp2, timestamp1); //60
Date.weekDiff(timestamp1, date2); //-60
Date.weekDiff(timestamp2, date1); //60
Date.weekDiff(date1, null); //null
Date.weekDiff(null, date2); //null
Date.weekDiff(timestamp1, null); //null
Date.weekDiff(null, timestamp2); //null
Date.weekDiff(null, null); //null
```



## quarterDiff

计算两个日期之间的季度差值

```javascript
Date.quarterDiff(d1, d2)
```

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

**返回值**

类型 `Integer`
计算两个日志之间相差的季度数。相等则会0，若d1在d2之前，则返回负值，反之返回正值

**示例**

```javascript
//假设date1的值为 2022-10-01 13:10:12，时间戳 timestamp 为 1667279412000
//假设date2的值为 2023-12-01 13:10:12，时间戳 timestamp 为 1701407412000

Date.quarterDiff(date1, date2); //-4
Date.quarterDiff(date2, date1); //4
Date.quarterDiff(timestamp1, timestamp2); //-4
Date.quarterDiff(timestamp2, timestamp1); //4
Date.quarterDiff(timestamp1, date2); //-4
Date.quarterDiff(timestamp2, date1); //4
Date.quarterDiff(date1, null); //null
Date.quarterDiff(null, date2); //null
Date.quarterDiff(timestamp1, null); //null
Date.quarterDiff(null, timestamp2); //null
Date.quarterDiff(null, null); //null
```

## getStartOfDay

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

```javascript
Date.getStartOfDay()
Date.getStartOfDay(date)
```

| 参数   | 类型     | 描述                     |
|------|--------|------------------------|
| date | `Date` | 可选，指定日期，默认为当前日期 |

**返回值**

类型 `Date` 指定日期的开始时间

**示例**

```javascript
Date.getStartOfDay() // 当前日期的 00:00:00.000
Date.getStartOfDay(new Date(2025-01-15 14:30:45)) // 2025-01-15 00:00:00.000
```

## getMonday

获取指定日期所在周的周一日期

```javascript
Date.getMonday()
Date.getMonday(date)
```

| 参数   | 类型     | 描述                     |
|------|--------|------------------------|
| date | `Date` | 可选，指定日期，默认为当前日期 |

**返回值**

类型 `Date` 指定日期所在周的周一日期（00:00:00.000）

**示例**

```javascript
// 假设当前日期是 2025-01-16（星期四）
Date.getMonday() // 2025-01-13 00:00:00.000（本周一）
Date.getMonday(new Date(2025-01-19)) // 2025-01-13 00:00:00.000（周日返回前一周的周一）
```

## getDateOfThisWeek

获取本周指定星期几的日期

```javascript
Date.getDateOfThisWeek(week)
```

| 参数   | 类型        | 描述                     |
|------|-----------|------------------------|
| week | `Integer` | 星期几，1=周一，2=周二，...，7=周日 |

**返回值**

类型 `Date` 本周指定星期几的日期（00:00:00.000）

**示例**

```javascript
// 假设当前日期是 2025-01-16（星期四）
Date.getDateOfThisWeek(1) // 2025-01-13 00:00:00.000（本周一）
Date.getDateOfThisWeek(5) // 2025-01-17 00:00:00.000（本周五）
Date.getDateOfThisWeek(7) // 2025-01-19 00:00:00.000（本周日）
```

## getStartOfMonth

获取指定日期所在月份的开始日期

```javascript
Date.getStartOfMonth()
Date.getStartOfMonth(date)
```

| 参数   | 类型     | 描述                     |
|------|--------|------------------------|
| date | `Date` | 可选，指定日期，默认为当前日期 |

**返回值**

类型 `Date` 指定日期所在月份的第一天（00:00:00.000）

**示例**

```javascript
Date.getStartOfMonth() // 当前月份的第一天
Date.getStartOfMonth(new Date(2025-03-15)) // 2025-03-01 00:00:00.000
```

## getStartOfYear

获取指定日期所在年份的开始日期

```javascript
Date.getStartOfYear()
Date.getStartOfYear(date)
```

| 参数   | 类型     | 描述                     |
|------|--------|------------------------|
| date | `Date` | 可选，指定日期，默认为当前日期 |

**返回值**

类型 `Date` 指定日期所在年份的第一天（00:00:00.000）

**示例**

```javascript
Date.getStartOfYear() // 当前年份的第一天
Date.getStartOfYear(new Date(2025-06-15)) // 2025-01-01 00:00:00.000
```

## isSameDay

判断两个日期是否为同一天

```javascript
Date.isSameDay(date1, date2)
```

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

**返回值**

类型 `Boolean` 两个日期是否为同一天

**示例**

```javascript
Date.isSameDay(new Date(2025-01-15 10:30:00), new Date(2025-01-15 14:45:00)) // true
Date.isSameDay(new Date(2025-01-15), new Date(2025-01-16)) // false
```

## timestampToDate

将时间戳转换为日期对象

```javascript
Date.timestampToDate(timestamp)
```

| 参数       | 类型       | 描述          |
|----------|----------|-------------|
| timestamp | `Long` 或 `String` | UNIX时间戳 |

**返回值**

类型 `Date` 日期对象，如果转换失败返回 `null`

**示例**

```javascript
Date.timestampToDate(1700000000000) // Date对象
Date.timestampToDate("1700000000000") // Date对象
Date.timestampToDate(null) // null
```

## dateToTimestamp

将日期对象转换为时间戳

```javascript
Date.dateToTimestamp(date)
```

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

**返回值**

类型 `Long` UNIX时间戳，如果日期为 `null` 则返回 `null`

**示例**

```javascript
Date.dateToTimestamp(new Date()) // 当前时间戳
Date.dateToTimestamp(null) // null
```

## formatDate

格式化日期为字符串

```javascript
Date.formatDate(date, format)
```

| 参数     | 类型       | 描述         |
|--------|----------|------------|
| date   | `Date` 或 `Long` | 日期对象或时间戳 |
| format | `String` | 日期格式      |

**返回值**

类型 `String` 格式化后的日期字符串，如果参数无效返回 `null`

**示例**

```javascript
Date.formatDate(new Date(), "yyyy-MM-dd") // "2025-01-15"
Date.formatDate(1700000000000, "yyyy/MM/dd HH:mm:ss") // "2023/11/14 21:13:20"
Date.formatDate(null, "yyyy-MM-dd") // null
```

## parseDate

将字符串解析为日期对象

```javascript
Date.parseDate(dateString, format)
```

| 参数         | 类型       | 描述     |
|------------|----------|--------|
| dateString | `String` | 日期字符串 |
| format     | `String` | 日期格式  |

**返回值**

类型 `Date` 日期对象，如果解析失败返回 `null`

**示例**

```javascript
Date.parseDate("2025-01-15", "yyyy-MM-dd") // Date对象
Date.parseDate("2025/01/15 14:30:00", "yyyy/MM/dd HH:mm:ss") // Date对象
Date.parseDate("invalid", "yyyy-MM-dd") // null
```

