zent
Version:
一套前端设计语言和基于React的实现
223 lines (174 loc) • 21.6 kB
Markdown
---
title: DatePicker
path: component/date-picker
group: Data Entry
---
## DatePicker
DateTime pickers, provides basic time choosing functionality.
### Guides
- Included pickers：`DatePicker`,`WeekPicker`,`MonthPicker`,`QuarterPicker`,`YearPicker`,`DateRangePicker`,`CombinedDateRangePicker`,`TimePicker`,`TimeRangePicker` , `CombinedTimeRangePicker` ,`SingleCalendarDatePanelPicker` and `CombinedPanelRangePicker`
- `DatePicker` ,`CombinedDateRangePicker` , `DateRangePicker` , `SingleCalendarDatePanelPicker` and `CombinedPanelRangePicker` can use `showTime` to allow time selection.
### API
#### Common API
| Property | Description | Type | Default | Required |
| ------------ | ------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------- | -------- |
| value | Selected date | - | - | Yes |
| onChange | Callback when the selected time is changing | - | - | Yes |
| valueType | Set `onChange`'s value type, options:`'string'` \| `'number'` \| `'date'` | `string` | `'string'` | No |
| format | Format string date | `string` | Different pickers have different values | No |
| disabledDate | Specify the date that cannot be selected | `(date: Date) => {}` \| `IDisableDateMap` | - | No |
| defaultDate | Default date value | `string` \| `Date` \| `number` | `new Date()` | No |
| disabled | Determine whether the DatePicker is disabled | `boolean` | `false` | No |
| canClear | Whether the date can be cleared | `boolean` | `true` | No |
| openPanel | The open state of picker | `boolean` | `false` | No |
| onOpen | Callback when the popup is popped up | `function` | - | No |
| onClose | Callback when the popup is closed | `function` | - | No |
| width | To set the width of input | `string` \| `number` | - | No |
| className | Cusotm className | `string` | `''` | No |
```ts
interface IDisableDateMap {
min?: string | Date | number; // The minimium selectable date
max?: string | Date | number; // The maximum selectable date
}
```
#### DatePicker API
| Property | Description | Type | Default | Required |
| ------------ | ------------------------------------------- | ---------------------------------------- | ------------------------ | -------- |
| value | Selected date | `string` \| `Date` \| `number` | - | Yes |
| onChange | Callback when the selected date is changing | `(date: string | Date | number) => {}` | - | Yes |
| placeholder | The placeholder of date input | `string` | `'Please select a date'` | No |
| format | To set the date format | `string` | `'YYYY-MM-DD'` | No |
| hideFooter | Whether to show footer | `boolean` | `false` | No |
| showTime | To provide an additional time selection | `boolean` \| `object` | `false` | No |
| disabledTime | To specify the time that cannot be selected | `(date?: Date) => IDisabledTimeOption` | - | No |
| showLunarDate | Whether to display lunar date | `boolean` | `false` | No |
| lunarValueFormatter | Format lunar date backfill value | `(date: Date) => string` | - | No |
**Additional**
- When return value of `showTime` is an object, to provide an additional time selection, there are some properties within this object: `format`、`hourStep`、`minuteStep`、`secondStep`, but redefines the type of `defaultTime` to be `string | (date: Date) => string`
- `disabledTime` only works with `showTime`, see the details in `TimePicker`
- `format` should be `'YYYY-MM-DD HH:mm:ss'` when `showTime` is `true`
- `lunarValueFormatter` only works with `showLunarDate`
#### WeekPicker API
| Property | Description | Type | Default | Required |
| ------------ | ------------------------------------------- | ----------------------------------------------- | ------------------------ | -------- |
| value | Selected date | `Array<string | Date | number>` | - | Yes |
| onChange | Callback when the selected date is changing | `(date: Array<string | Date | number>) => {}` | - | Yes |
| placeholder | The placeholder of date input | `string` | `'Please select a week'` | No |
| weekStartsOn | To set the start day of a week | `WeekStartsOnMap` | `WeekStartsOnMap.Monday` | No |
| format | To set the date format | `string` | `'YYYY-MM-DD'` | No |
| hideFooter | Whether to show footer | `boolean` | `false` | No |
**Additional**
- `value` is a range of dates in `WeekPicker`
- `weekStartsOnMap`: `Monday`、`Tuesday`、`Wednesday`、`Thursday`、`Friday`、`Saturday`、`Sunday`
#### YearPicker / MonthPicker API
| Property | Description | Type | Default | Required |
| ----------- | ------------------------------------------- | ---------------------------------------- | ----------------------------------------------------- | -------- |
| value | Selected date | `string` \| `Date` \| `number` | - | Yes |
| onChange | Callback when the selected date is changing | `(date: string | Date | number) => {}` | - | Yes |
| placeholder | The placeholder of date input | string | `'Please select a year'` \| `'Please select a month'` | No |
| format | To set the date format | string | `'YYYY'` \| `'YYYY-MM'` | No |
**Additional**
- `value` is a single date in `YearPicker` / `MonthPicker`
#### QuarterPicker API
| Property | Description | Type | Default | Required |
| ----------- | ------------------------------------------- | ----------------------------------------------- | --------------------------- | -------- |
| value | Selected date | `Array<string | Date | number>` | - | Yes |
| onChange | Callback when the selected date is changing | `(date: Array<string | Date | number>) => {}` | - | Yes |
| placeholder | The placeholder of date input | `string` | `'Please select a quarter'` | No |
| format | To set the date format | `string` | `'YYYY-MM'` | No |
**Additional**
- `value` is a single date in `QuarterPicker`
#### TimePicker API
| Property | Description | Type | Default | Required |
| ------------ | ------------------------------------------- | --------------------------- | ------------------------ | -------- |
| value | Selected time | `string` | - | Yes |
| onChange | Callback when the selected time is changing | `(date: string ) => {}` | - | Yes |
| defaultTime | To set default time | `string` | - | No |
| placeholder | The placeholder of time input | `string` | `'Please select a time'` | No |
| format | To set the time format | `string` | `'HH:mm:ss'` | No |
| disabledTime | To specify the time that cannot be selected | `() => IDisabledTimeOption` | - | No |
| hourStep | Interval between hours in picker | `number` | `1` | No |
| minuteStep | Interval between minutes in picker | `number` | `1` | No |
| secondStep | Interval between seconds in picker | `number` | `1` | No |
```ts
interface IDisabledTimeOption {
disabledHours?: () => number[];
disabledMinutes: (hour: number) => number[];
disabledSeconds?: (hour: number, minute: number) => number[];
}
```
### SingleCalendarDatePanelPicker API
| Property | Description | Type | Default | Required |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------- | -------- |
| selected | Selected date | `Date\|null` | - | 是 |
| onSelected | Callback when the selected date is changing | `(date: Date ) => {}` | - | 是 |
| defaultPanelDate | The default Date of panel | `Date` | - | 否 |
| disabledPanelDate | The disabled Date | `(date:Date) => boolean` | - | 是 |
| onChangePanel | The callback function of the type of switch panel | `(type:IPickerType) => {}` | - | 否 |
| onPanelDateChange | Callback function for the value of the toggle panel | `(date:Date) => {}` | - | 否 |
| hideFooter | Should hide the footer of panel | `boolean` | `false` | 否 |
| showTime | To provide an additional time | `boolean` \| `object` | `false` | 否 |
| disabledTime | To specify the time that cannot be selected | `(date?: Date) => IDisabledTimeOption` | - | 否 |
| popText | The content when selected a date cell | `string` | - | 否 |
| footerText | The content on the footer to dump to now | `string` | - | 否 |
| combinedLeft | Whether it is the left calendar of the combined calendar panel, if yes, hide the next month/year icon at the top right of this component | `boolean` | false | 否 |
| combinedRight | Whether it is the right calendar of the combined calendar panel, if yes, hide the next month/year icon at the top left of this component | `boolean` | false | 否 |
| hoverRangeDate | The date range for hover | `[Date,Date]\|null` | - | 否 |
| rangeDate | The date range has been selected | `[Date,Date]\|null` | - | 否 |
#### DateRangePicker / CombinedDateRangePicker （Base on DatePicker）
| Property | Description | Type | Default | Required |
| ----------- | ------------------------------------------------- | ----------------------------------------------- | --------------------------- | -------- |
| value | Selected date range | `Array<string | Date | number>` | - | Yes |
| onChange | Callback when the selected date range is changing | `(date: Array<string | Date | number>) => {}` | - | Yes |
| placeholder | The placeholder of dates input | `[string, string]` | `['Start date','End date']` | No |
| defaultDate | Default date range | `[string, string]` | - | No |
| dateSpan | Quick set the time span | `number` | - | No |
**Additional**
- When return value of `showTime` is an object, `defaultTime` should be `[string | (date: Date) => string, string | (date: Date) => string]`. (default: ['00:00:00','23:59:59'])
- `disabledDate(val, type)` or `disabledTime(val, type)`, the `type` is `'start' | 'end'`
- Only supports `dateSpan` for `DateRangePicker` and `CombinedDateRangePicker`.
- Definition of `disabled` and `canClear` is `boolean | boolean[]` in `DateRangePicker`.
### CombinedPanelRangePicker （基于 DateRangePicker 和 TimePicker ）
| Property | Description | Type | Default | Required |
| --------------- | ------------------------------------------------------------------------- | ---------------------------------------------- | -------------- | -------- |
| value | Selected date range | `Array<string \| Date \| number>\| null` | - | Yes |
| onChange | Callback when the selected date range is changing | `(date: Array<string \| Date\| number>) => {}` | - | Yes |
| defaultDate | Default date value | `[string, string]` | - | No |
| dateSpan | Quick set the time span | `number` | - | No |
| valueType | Set `onChange`'s value type, options:`'string'` \| `'number'` \| `'date'` | `string` | `'string'` | No |
| format | Format string | `string` | `'YYYY-MM-DD'` | No |
| disabledDate | Specify the date that cannot be selected | `(date: Date) => {}` \| `IDisableDateMap` | - | No |
| showTime | To provide an additional time selection | `boolean` \| `object` | `false` | No |
| hideConfirm | hide confirm button in additional time selection | `boolean` | `false` | No |
| className | the class of this component | `string` | - | No |
| leftClassName | the class of the left calendar | `string` | - | No |
| rightClassName | the class of the right calendar | `string` | - | No |
| footerClassName | the class of the additional time selection | `string` | - | No |
**Additional**
- When return value of `showTime` is an object, `defaultTime` should be `[string | (date: Date) => string, string | (date: Date) => string]`. (default: ['00:00:00','23:59:59'])
- `disabledDate(val, type)` or `disabledTime(val, type)`, the `type` is `'start' | 'end'`
#### TimeRangePicker / CombinedTimeRangePicker API （Base on TimePicker）
| Property | Description | Type | Default | Required |
| ----------- | ------------------------------------------- | --------------------------------- | --------------------------- | -------- |
| value | Selected time | `[string, string]` | - | Yes |
| onChange | Callback when the selected time is changing | `(date: [string, string] ) => {}` | - | Yes |
| defaultTime | To set default time | `[string, string]` | - | No |
| placeholder | The placeholder of time input | `[string, string]` | `['Start time','End time']` | No |
**Additional**
- `disabledTime(val, type)`, the `type` is `'start' | 'end'`
#### Functions
- Provide some useful functions: e.g. `disabledTimeWithRange`、`getDisabledDateAndTimeWithRangeProps`, that can use in your `disabledTime` handlers. You need to manually import them from `zent/es/date-picker/disabledHelpers`.
#### Format string
| | Format character | Output |
| --------- | ---------------- | ---------------------------------------- |
| **Year** | YY | 70 71 ... 29 30 |
| | YYYY | 1970 1971 ... 2029 2030 |
| **Month** | M | 1 2 ... 11 1 |
| | MM | 01 02 ... 11 12 |
| | MMM | Jan, Feb ... Nov, Dec |
| | MMMM | January, February ... November, December |
| **Date** | D | 1 2 ... 30 31 |
| | DD | 01 02 ... 30 31 |
| | d | 0 1 ... 5 6 |
| | ddd | Sun, Mon ... Fri, Sat |
| | dddd | Sunday, Monday ... Friday, Saturday |