---
title: DatePicker
subtitle: 日期时间选择
path: component/date-picker
group: 信息录入
---

## DatePicker

时间选择组件, 提供基础的时间、日期、日期时间筛选功能。

### 使用指南

- 包含以下组件：`DatePicker`、`WeekPicker`、`MonthPicker`、`QuarterPicker`、`YearPicker`、`DateRangePicker`、`CombinedDateRangePicker`、`TimePicker`、`TimeRangePicker`、`CombinedTimeRangePicker` 、 `SingleCalendarDatePanelPicker` 和 `CombinedPanelRangePicker`。
- `DatePicker` 、`CombinedDateRangePicker`、`DateRangePicker` 、`SingleCalendarDatePanelPicker` 和 `CombinedPanelRangePicker` 可以通过 `showTime` 属性来支持时间的选择。

### API

#### 共用的日期组件 API

| 参数         | 说明                                                                  | 类型                                      | 默认值                   | 是否必须 |
| ------------ | --------------------------------------------------------------------- | ----------------------------------------- | ------------------------ | -------- |
| value        | 选择的日期                                                            | -                                         | -                        | 是       |
| onChange     | 选择日期回调函数                                                      | -                                         | -                        | 是       |
| valueType    | onChange 返回日期的类型，可选值：`'string'` \| `'number'` \| `'date'` | `string`                                  | `'string'`               | 否       |
| format       | 设置字符串日期的格式                                                  | `string`                                  | 不同组件默认值不同，下详 | 否       |
| disabledDate | 不可选择的日期                                                        | `(date: Date) => {}` \| `IDisableDateMap` | -                        | 否       |
| defaultDate  | 默认面板日期                                                          | `string` \| `Date` \| `number`            | `new Date()`             | 否       |
| disabled     | 禁用状态                                                              | `boolean`                                 | `false`                  | 否       |
| canClear     | 日期是否可清除                                                        | `boolean`                                 | `true`                   | 否       |
| openPanel    | 控制面板是否打开                                                      | `boolean`                                 | `false`                  | 否       |
| onOpen       | 面板打开的回调                                                        | `function`                                | -                        | 否       |
| onClose      | 面板关闭的回调                                                        | `function`                                | -                        | 否       |
| width        | 组件 input 的 宽度                                                    | `string` \| `number`                      | -                        | 否       |
| className    | 自定义样式类                                                          | `string`                                  | `''`                     | 否       |

```ts
interface IDisableDateMap {
	min?: string | Date | number; // 最小可选日期
	max?: string | Date | number; // 最大可选日期
}
```

**注意：**

- `value` 和 `onChange` 必须同时提供

### DatePicker 其他 API

| 参数         | 说明                 | 类型                                     | 默认值         | 是否必须 |
| ------------ | -------------------- | ---------------------------------------- | -------------- | -------- |
| value        | 选择的日期           | `string` \| `Date` \| `number`           | -              | 是       |
| onChange     | 选择日期回调函数     | `(date: string | Date | number) => {}` | -              | 是       |
| placeholder  | 输入框提示文字       | `string`                                 | `'请选择日期'` | 否       |
| format       | 设置字符串日期的格式 | `string`                                 | `'YYYY-MM-DD'` | 否       |
| hideFooter   | 隐藏面板底部         | `boolean`                                | `false`        | 否       |
| showTime     | 是否支持时间选择功能 | `boolean` \| `object`                    | `false`        | 否       |
| disabledTime | 时间禁用判断         | `(date?: Date) => IDisabledTimeOption`   | -              | 否       |
| showLunarDate       | 是否显示农历日期     | `boolean`                              | `false`        | 否             |
| lunarValueFormatter | 格式化农历日期回填值 | `(date: Date) => string`               | -              | 否             |

**注意：**

- `showTime` 为对象时，表示支持时间选择，具体属性可参考 `TimePicker`，包括 `format`、`hourStep`、`minuteStep`、`secondStep`，其中 `defaultTime` 类型定义为 `string | (date: Date) => string`
- `disabledTime` 在 `showTime` 开启时生效，可参考 `TimePicker` 的 `IDisabledTimeOption`
- `showTime` 时 `format` 值应为`'YYYY-MM-DD HH:mm:ss'`，使用时注意 `format` 参数
- `showTime` 时 `format` 值应为`'YYYY-MM-DD HH:mm:ss'`，使用时注意 `format` 参数
- `lunarValueFormatter` 在 `showLunarDate` 开启时生效

### WeekPicker 其他 API

| 参数         | 说明                 | 类型                                            | 默认值                   | 是否必须 |
| ------------ | -------------------- | ----------------------------------------------- | ------------------------ | -------- |
| value        | 选择的日期           | `Array<string | Date | number>`               | -                        | 是       |
| onChange     | 选择日期回调函数     | `(date: Array<string | Date | number>) => {}` | -                        | 是       |
| placeholder  | 输入框提示文字       | `string`                                        | `'请选择自然周'`         | 否       |
| weekStartsOn | 一周的开始           | `WeekStartsOnMap`                               | `WeekStartsOnMap.Monday` | 否       |
| format       | 设置字符串日期的格式 | `string`                                        | `'YYYY-MM-DD'`           | 否       |
| hideFooter   | 隐藏面板底部         | `boolean`                                       | `false`                  | 否       |

**注意：**

- `WeekPicker` 的 `value` 和 `onChange` 回调日期均为数组
- `WeekStartsOnMap` 枚举： `'Sunday'`、`'Monday'`、`'Tuesday'`、`'Wednesday'`、`'Thursday'`、`'Friday'`、`'Saturday'`

### YearPicker / MonthPicker 其他 API

| 参数        | 说明                 | 类型                                     | 默认值                           | 是否必须 |
| ----------- | -------------------- | ---------------------------------------- | -------------------------------- | -------- |
| value       | 选择的日期           | `string` \| `Date` \| `number`           | -                                | 是       |
| onChange    | 选择日期回调函数     | `(date: string | Date | number) => {}` | -                                | 是       |
| placeholder | 输入框提示文字       | `string`                                 | `'请选择年份'` \| `'请选择月份'` | 否       |
| format      | 设置字符串日期的格式 | `string`                                 | `'YYYY'` \| `'YYYY-MM'`          | 否       |

**注意：**

- `YearPicker` / `MonthPicker` 的 `value` 和 `onChange` 回调日期均为单个日期

### QuarterPicker 其他 API

| 参数        | 说明                 | 类型                                            | 默认值         | 是否必须 |
| ----------- | -------------------- | ----------------------------------------------- | -------------- | -------- |
| value       | 选择的日期           | `Array<string | Date | number>`               | -              | 是       |
| onChange    | 选择日期回调函数     | `(date: Array<string | Date | number>) => {}` | -              | 是       |
| placeholder | 输入框提示文字       | `string`                                        | `'请选择季度'` | 否       |
| format      | 设置字符串日期的格式 | `string`                                        | `'YYYY-MM'`    | 否       |

**注意：**

- `QuarterPicker` 的 `value` 和 `onChange` 回调日期均为数组

### TimePicker API

| 参数         | 说明                                  | 类型                        | 默认值         | 是否必须 |
| ------------ | ------------------------------------- | --------------------------- | -------------- | -------- |
| value        | 时间                                  | `string`                    | -              | 是       |
| onChange     | 选择时间回调函数                      | `(date: string ) => {}`     | -              | 是       |
| defaultTime  | 默认时间                              | `string`                    | -              | 否       |
| placeholder  | 输入框提示文字                        | `string`                    | `'请选择时间'` | 否       |
| format       | 返回的时间的格式 （决定面板展示的列） | `string`                    | `'HH:mm:ss'`   | 否       |
| disabledTime | 时间禁用判断                          | `() => IDisabledTimeOption` | -              | 否       |
| hourStep     | 小时选项间隔                          | `number`                    | `1`            | 否       |
| minuteStep   | 分钟选项间隔                          | `number`                    | `1`            | 否       |
| secondStep   | 秒选项间隔                            | `number`                    | `1`            | 否       |

```ts
interface IDisabledTimeOption {
	disabledHours?: () => number[];
	disabledMinutes: (hour: number) => number[];
	disabledSeconds?: (hour: number, minute: number) => number[];
}
```

### SingleCalendarDatePanelPicker API

| 参数              | 说明                                                                | 类型                                   | 默认值  | 是否必须 |
| ----------------- | ------------------------------------------------------------------- | -------------------------------------- | ------- | -------- |
| selected          | 日期                                                                | `Date\|null`                           | -       | 是       |
| onSelected        | 选择时间回调函数                                                    | `(date: Date ) => {}`                  | -       | 是       |
| defaultPanelDate  | 默认面板日期                                                        | `Date`                                 | -       | 否       |
| disabledPanelDate | 日期禁用判断                                                        | `(date:Date) => boolean`               | -       | 是       |
| onChangePanel     | 切换面板日期的回调                                                  | `(type:IPickerType) => {}`             | -       | 否       |
| onPanelDateChange | 切换面板日期后，具体面板日期的回调                                  | `(date:Date) => {}`                    | -       | 否       |
| hideFooter        | 隐藏面板底部                                                        | `boolean`                              | `false` | 否       |
| showTime          | 是否支持时间选择功能                                                | `boolean` \| `object`                  | `false` | 否       |
| disabledTime      | 时间禁用判断                                                        | `(date?: Date) => IDisabledTimeOption` | -       | 否       |
| popText           | 选中日期后的 pop 文案                                               | `string`                               | -       | 否       |
| footerText        | 底部定位到现在的快捷按钮文案                                        | `string`                               | -       | 否       |
| combinedLeft      | 是否为组合日历面板的左侧日历，是则隐藏本组件顶部右侧的下个月/下一年 		| `boolean`                              | false   | 否       |
| combinedRight     | 是否为组合日历面板的右侧日历，是则隐藏本组件顶部左侧的下个月/下一年		 | `boolean`                              | false   | 否       |
| hoverRangeDate    | 指定 hover 的日期区域                                               | `[Date,Date]\|null`                    | -       | 否       |
| rangeDate         | 已选中的日期区域                                                    | `[Date,Date]\|null`                    | -       | 否       |


```ts
interface IDisabledTimeOption {
	disabledHours?: () => number[];
	disabledMinutes: (hour: number) => number[];
	disabledSeconds?: (hour: number, minute: number) => number[];
}
```

### DateRangePicker / CombinedDateRangePicker API （基于 DatePicker）

| 参数        | 说明             | 类型                                            | 默认值                    | 是否必须 |
| ----------- | ---------------- | ----------------------------------------------- | ------------------------- | -------- |
| value       | 选择的日期       | `Array<string | Date | number>`               | -                         | 是       |
| onChange    | 选择日期回调函数 | `(date: Array<string | Date | number>) => {}` | -                         | 是       |
| placeholder | 输入框提示文字   | `[string, string]`                              | `['开始日期','结束日期']` | 否       |
| defaultDate | 默认面板日期     | `[string, string]`                              | -                         | 否       |
| dateSpan    | 日期跨度         | `number`                                      | -                         | 否       |

**注意：**

- `showTime` 为对象时，`defaultTime` 类型为 `[string | (date: Date) => string, string | (date: Date) => string]`，表示默认开始时间和默认结束时间（不填为['00:00:00','23:59:59']）
- `disabledDate`、`disabledTime` 回调方法的第二个参数均为`type?: 'start' | 'end'`
- `dateSpan` 仅 `DateRangePicker` 和 `CombinedDateRangePicker` 组件可用
- `DateRangePicker` 的 `disabled` 、 `canClear` 属性类型为 `boolean | boolean[]`

### CombinedPanelRangePicker （基于 DateRangePicker 和 TimePicker ）

| 参数             | 说明                                                                  | 类型                                            | 默认值         | 是否必须 |
| --------------- | --------------------------------------------------------------------- | ----------------------------------------------- | -------------- | -------- |
| value           | 选择的日期                                                              | `Array<string \| Date \| number>\|null`         | -              | 是       |
| onChange        | 选择日期回调函数                                                         | `(date: Array<string \| Date \| number>) => {}` | -              | 是       |
| defaultDate     | 默认面板日期                                                            | `[string, string]`                              | -              | 否       |
| dateSpan        | 日期跨度                                                               | `number`                                        | -              | 否       |
| valueType       | onChange 返回日期的类型，可选值：`'string'` \| `'number'` \| `'date'`     | `string`                                        | `'string'`     | 否       |
| format          | 设置字符串日期的格式                                                     | `string`                                        | `'YYYY-MM-DD'` | 否       |
| disabledDate    | 不可选择的日期                                                           | `(date: Date) => {}` \| `IDisableDateMap`      | -              | 否       |
| showTime        | 是否支持时间选择功能                                                     | `boolean` \| `object`                           | `false`        | 否       |
| hideConfirm      | 如果开启了 showTime，是否要隐藏 footer 的“确定”按钮                        | `boolean`                                       | `false`        | 否       |
| className       | 整个组件的 class                                                       | `string`                                         | -              | 否       |
| leftClassName   | 左侧日历的 class                                                       | `string`                                         | -              | 否       |
| rightClassName  | 右侧日历的 class                                                       | `string`                                         | -              | 否       |
| footerClassName | 如果开启了 showTime，footer 组件的 class                                | `string`                                         | -              | 否       |


**注意：**

- `showTime` 为对象时，`defaultTime` 类型为 `[string | (date: Date) => string, string | (date: Date) => string]`，表示默认开始时间和默认结束时间（不填为['00:00:00','23:59:59']）
- `disabledDate`、`disabledTime` 回调方法的第二个参数均为`type?: 'start' | 'end'`



### TimeRangePicker / CombinedTimeRangePicker API （基于 TimePicker）

| 参数        | 说明             | 类型                              | 默认值                     | 是否必须 |
| ----------- | ---------------- | --------------------------------- | -------------------------- | -------- |
| value       | 时间             | `[string, string]`                | -                          | 是       |
| onChange    | 选择时间回调函数 | `(date: [string, string] ) => {}` | -                          | 是       |
| defaultTime | 默认时间         | `[string, string]`                | -                          | 否       |
| placeholder | 输入框提示文字   | `[string, string]`                | `['开始时间', '结束时间']` | 否       |

**注意：**

- `disabledTime` 回调方法的第二个参数均为`type?: 'start' | 'end'`

### 工具函数
- 提供时间禁用的处理方法：`disabledTimeWithRange`、`getDisabledDateAndTimeWithRangeProps` 等，需要从 `zent/es/date-picker/disabledHelpers` 引入。

#### 格式化字符表

|           | 字符 | 输出                              |
| --------- | ---- | --------------------------------- |
| **Year**  | YY   | 70 71 ... 29 30                   |
|           | YYYY | 1970 1971 ... 2029 2030           |
| **Month** | M    | 1 2 ... 11 1                      |
|           | MM   | 01 02 ... 11 12                   |
|           | MMM  | 1 月, 2 月 ... 11 月, 12 月       |
|           | MMMM | 一月, 二月 ... 十一月, 十二月     |
| **Date**  | D    | 1 2 ... 30 31                     |
|           | DD   | 01 02 ... 30 31                   |
|           | d    | 0 1 ... 5 6                       |
|           | ddd  | 周日, 周一 ... 周五, 周六         |
|           | dddd | 星期日, 星期一 ... 星期五, 星期六 |
