## 简介

日期选择器常用于完成日期信息的录入，包括录入指定日期、指定日期区间等类型信息，常见的日期展示格式包括：

简短版：
月 + 日：07-25
年 + 月：2020-07

标准版：
年 + 月 + 日（中）：2020-07-25
年 + 月 + 日（英）：2020-Jul-25

完整版：
年 + 月 + 日（中）：2020年7月25日
年 + 月 + 日（英）：July 25, 2020

## 示例

```tsx
import React from 'react';
import { DatePicker } from '@alicloud/console-components';
import moment from 'moment';

const titleStyle = {
  margin: '40px 0 4px',
  color: '#1D1D1F',
  height: 20,
};
const onChange = (val) => console.log(val);
const startValue = moment('2017-11-20', 'YYYY-MM-DD', true);

export default () => {
  return (
    <div>
      <div style={titleStyle}>默认</div>
      <DatePicker onChange={onChange} format="YYYY-MM-DD" />
      <div style={titleStyle}>完成选择</div>
      <DatePicker
        onChange={onChange}
        defaultValue={startValue}
        format="YYYY-MM-DD"
      />
      <div style={titleStyle}>禁用</div>
      <DatePicker onChange={onChange} disabled />
    </div>
  );
};

export const meta = {
  title: '日期选择交互',
  describe:
    '可以通过 defaultValue 属性为日期选择器提供初值，所提供的初值必须为 moment 对象。',
};

```

```tsx
import React from 'react';
import { DatePicker } from '@alicloud/console-components';
import moment from 'moment';

const titleStyle = {
  margin: '40px 0 4px',
  color: '#1D1D1F',
  height: 20,
};
const onChange = (val) => console.log(val);
const startValue = moment('2017-11-20', 'YYYY-MM-DD', true);

export default () => {
  return (
    <div>
      <div style={titleStyle}>默认</div>
      <DatePicker onChange={onChange} format="YYYY-MM-DD" showTime />
      <div style={titleStyle}>完成选择</div>
      <DatePicker
        onChange={onChange}
        defaultValue={startValue}
        format="YYYY-MM-DD"
        showTime
      />
      <div style={titleStyle}>禁用</div>
      <DatePicker onChange={onChange} disabled showTime />
    </div>
  );
};

export const meta = {
  title: '日期与时间选择交互',
  describe:
    '如果需要同时选择时间，可以通过 showTime 属性开启，showTime 支持传入 TimePickerPanel 的属性，例如 format, defaultValue 等。',
};

```

```tsx
import React from 'react';
import { DatePicker } from '@alicloud/console-components';
import moment from 'moment';

const titleStyle = {
  margin: '4px 0 4px',
  color: '#1D1D1F',
  height: 20,
};

const contentStyle = {
  display: 'grid',
  gridTemplateColumns: 'repeat(2, 1fr)',
  gap: 36,
};

const startValue = moment('2020-07-25', 'YYYY-MM-DD', true);
export default () => {
  return (
    <div style={contentStyle}>
      <div>
        <div style={titleStyle}>简短</div>
        月+日&nbsp;
        <DatePicker defaultValue={startValue} format="MM-DD" />
        <br />
        <br />
        年+月&nbsp;
        <DatePicker defaultValue={startValue} format="YYYY-MM" />
      </div>
      <div>
        <div style={titleStyle}>标准</div>
        年+月+日（中）&nbsp;
        <DatePicker defaultValue={startValue} format="YYYY-MM-DD" />
        <br />
        <br />
        年+月+日（英）&nbsp;
        <DatePicker defaultValue={startValue} />
      </div>
      <div>
        <div style={titleStyle}>完整</div>
        年+月+日（中）&nbsp;
        <DatePicker defaultValue={startValue} format="YYYY年MM月DD日" />
        <br />
        <br />
        年+月+日（英）&nbsp;
        <DatePicker defaultValue={startValue} />
      </div>
    </div>
  );
};

export const meta = {
  title: '日期与时间选择交互',
  describe: '通过format属性控制日期格式。',
};

```

## API

### DatePicker

| 参数                 | 说明                                                                     | 类型                                                               | 默认值   | 是否必填 |
| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ | -------- | -------- |
| label                | 输入框内置标签                                                           | React.ReactNode                                                    | -        |          |
| state                | 输入框状态                                                               | 'success' | 'loading' | 'error'                                  | -        |          |
| placeholder          | 输入提示                                                                 | string                                                             | -        |          |
| defaultVisibleMonth  | 默认展现的月                                                             | () => Moment                                                       | -        |          |
| defaultVisibleYear   | 默认展现的年                                                             | () => Moment                                                       | -        |          |
| value                | 日期值（受控）moment 对象                                                | string | Moment | null                                           | -        |          |
| defaultValue         | 初始日期值，moment 对象                                                  | string | Moment | null                                           | -        |          |
| format               | 日期值的格式（用于限定用户输入和展示）                                   | string                                                             | moment().localeData().longDateFormat('ll') |          |
| showTime             | 是否使用时间控件，传入 TimePicker 的属性 { defaultValue, format, ... } | TimePickerProps | boolean                                         | false    |          |
| resetTime            | 每次选择日期时是否重置时间（仅在 showTime 开启时有效）                   | boolean                                                            | false    |          |
| disabledDate         | 禁用日期函数                                                             | (date: Moment, view: string) => boolean                            | -        |          |
| footerRender         | 自定义面板页脚                                                           | () => React.ReactNode                                              | -        |          |
| onChange             | 日期值改变时的回调                                                       | (value: string | Moment | null) => void                          | -        |          |
| onOk                 | 点击确认按钮时的回调                                                     | (value: string | Moment | null) => void                          | -        |          |
| size                 | 输入框尺寸                                                               | 'small' | 'medium' | 'large'                                     | 'medium' |          |
| disabled             | 是否禁用                                                                 | boolean                                                            | -        |          |
| hasClear             | 是否显示清空按钮                                                         | boolean                                                            | true     |          |
| visible              | 弹层显示状态                                                             | boolean                                                            | -        |          |
| defaultVisible       | 弹层默认是否显示                                                         | boolean                                                            | false    |          |
| onVisibleChange      | 弹层展示状态变化时的回调                                                 | (visible: boolean, reason: string) => void                         | -        |          |
| onVisibleMonthChange | 弹层展示月份变化时的回调                                                 | (value: Moment, reason: string) => void                            | -        |          |
| popupTriggerType     | 弹层触发方式                                                             | 'click' | 'hover'                                                 | 'click'  |          |
| popupAlign           | 弹层对齐方式，具体含义见 OverLay 文档                                    | string                                                             | 'tl tl'  |          |
| popupContainer       | 弹层容器                                                                 | PopupProps\['container']                                            | -        |          |
| popupStyle           | 弹层自定义样式                                                           | React.CSSProperties                                                | -        |          |
| popupClassName       | 弹层自定义样式类                                                         | string                                                             | -        |          |
| popupProps           | 弹层其他属性                                                             | React.PropsWithRef\<PopupProps>                                    | -        |          |
| inputProps           | 输入框其他属性                                                           | InputProps                                                         | -        |          |
| dateCellRender       | 自定义日期渲染函数                                                       | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| monthCellRender      | 自定义月份渲染函数                                                       | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| yearCellRender       | 自定义年份渲染函数                                                       | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| dateInputAriaLabel   | 日期输入框的 aria-label 属性                                             | string                                                             | -        |          |
| timeInputAriaLabel   | 时间输入框的 aria-label 属性                                             | string                                                             | -        |          |
| isPreview            | 是否为预览态                                                             | boolean                                                            | -        |          |
| renderPreview        | 预览态定制渲染函数                                                       | (value: Moment | null, props: DatePickerProps) => React.ReactNode | -        |          |
| followTrigger        | 是否跟随滚动                                                             | boolean                                                            | -        |          |
| popupComponent       | 自定义弹层                                                               | React.ComponentType\<unknown>                                      | -        |          |
| popupContent         | 自定义弹层内容                                                           | React.ReactElement                                                 | -        |          |
| disableChangeMode    | 禁用日期选择器的日期模式切换                                             | boolean                                                            | -        |          |
| yearRange            | 年份范围，\[START\_YEAR, END\_YEAR]                                         | \[start: number, end: number]                                       | -        |          |

### DatePicker.MonthPicker

| 参数               | 说明                                   | 类型                                                     | 默认值   | 是否必填 |
| ------------------ | -------------------------------------- | -------------------------------------------------------- | -------- | -------- |
| label              | 输入框内置标签                         | React.ReactNode                                          | -        |          |
| state              | 输入框状态                             | 'success' | 'loading' | 'error'                        | -        |          |
| placeholder        | 输入提示                               | string                                                   | -        |          |
| defaultVisibleYear | 默认展现的年                           | () => Moment | null                                     | -        |          |
| value              | 日期值（受控）moment 对象              | string | Moment | null                                 | -        |          |
| defaultValue       | 初始日期值，moment 对象                | string | Moment | null                                 | -        |          |
| format             | 日期值的格式（用于限定用户输入和展示） | string                                                   | 'YYYY'    |          |
| disabledDate       | 禁用日期函数                           | (date: Moment, view: string) => boolean                  | -        |          |
| footerRender       | 自定义面板页脚                         | () => React.ReactNode                                    | -        |          |
| onChange           | 日期值改变时的回调                     | (value: Moment | string | null) => void                | -        |          |
| size               | 输入框尺寸                             | 'small' | 'medium' | 'large'                           | 'medium' |          |
| disabled           | 是否禁用                               | boolean                                                  | -        |          |
| hasClear           | 是否显示清空按钮                       | boolean                                                  | true     |          |
| visible            | 弹层显示状态                           | boolean                                                  | -        |          |
| defaultVisible     | 弹层默认是否显示                       | boolean                                                  | -        |          |
| onVisibleChange    | 弹层展示状态变化时的回调               | (visible: boolean, reason: string) => void               | -        |          |
| popupTriggerType   | 弹层触发方式                           | 'click' | 'hover'                                       | 'click'  |          |
| popupAlign         | 弹层对齐方式，具体含义见 OverLay 文档  | string                                                   | 'tl tl'  |          |
| popupContainer     | 弹层容器                               | PopupProps\['container']                                  | -        |          |
| popupStyle         | 弹层自定义样式                         | React.CSSProperties                                      | -        |          |
| popupClassName     | 弹层自定义样式类                       | string                                                   | -        |          |
| popupProps         | 弹层其他属性                           | React.PropsWithRef\<PopupProps>                          | -        |          |
| popupComponent     | 自定义弹层                             | React.ComponentType\<unknown>                            | -        |          |
| popupContent       | 自定义弹层内容                         | React.ReactElement                                       | -        |          |
| followTrigger      | 是否跟随滚动                           | boolean                                                  | -        |          |
| inputProps         | 输入框其他属性                         | InputProps                                               | -        |          |
| monthCellRender    | 自定义月份渲染函数                     | (calendarDate: Moment) => React.ReactNode                | -        |          |
| dateInputAriaLabel | 日期输入框的 aria-label 属性           | string                                                   | -        |          |
| renderPreview      | 预览态定制渲染函数                     | (value: Moment | null, props: MonthPickerProps) => void | -        |          |
| yearCellRender     | 自定义年份渲染函数                     | (calendarDate: Moment) => React.ReactNode                | -        |          |
| isPreview          | 是否为预览态                           | boolean                                                  | -        |          |

### DatePicker.RangePicker

| 参数                    | 说明                                                                     | 类型                                                                                                                                                              | 默认值   | 是否必填 |
| ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| type                    | 日期范围类型                                                             | 'date' | 'month' | 'year'                                                                                                                                       | -        |          |
| defaultVisibleMonth     | 默认展示的起始月份                                                       | () => Moment | null                                                                                                                                              | -        |          |
| placeholder             | 输入提示                                                                 | Array\<string> | string                                                                                                                                          | -        |          |
| value                   | 日期范围值数组 \[moment, moment]                                          | \[start: Moment | string | null | undefined, end?: Moment | string | undefined | null]                                                                       | -        |          |
| defaultValue            | 初始的日期范围值数组 \[moment, moment]                                    | \[<br/> start: Moment | string | null | undefined,<br/> end?: Moment | string | undefined | null,<br/> ]                                                     | -        |          |
| format                  | 日期值的格式（用于限定用户输入和展示）                                   | string                                                                                                                                                            | -        |          |
| showTime                | 是否使用时间控件，传入 TimePicker 的属性 { defaultValue, format, ... } | | (Omit\<TimePickerProps, 'defaultValue'> & {<br/> defaultValue?: Moment | string | null | (Moment | string | null | undefined)\[];<br/> })<br/> | boolean | false    |          |
| resetTime               | 每次选择日期时是否重置时间（仅在 showTime 开启时有效）                   | boolean                                                                                                                                                           | false    |          |
| disabledDate            | 禁用日期函数                                                             | (date: Moment, view: string) => boolean                                                                                                                           | -        |          |
| footerRender            | 自定义面板页脚                                                           | () => React.ReactNode                                                                                                                                             | -        |          |
| onChange                | 日期范围值改变时的回调                                                   | (value: (string | Moment | null | undefined)\[]) => void                                                                                                        | -        |          |
| onOk                    | 点击确认按钮时的回调 返回开始时间和结束时间                              | (value: (string | Moment | null | undefined)\[]) => void                                                                                                        | -        |          |
| label                   | 输入框内置标签                                                           | React.ReactNode                                                                                                                                                   | -        |          |
| state                   | 输入框状态                                                               | 'error' | 'loading' | 'success'                                                                                                                                 | -        |          |
| size                    | 输入框尺寸                                                               | 'small' | 'medium' | 'large'                                                                                                                                    | 'medium' |          |
| disabled                | 是否禁用                                                                 | boolean                                                                                                                                                           | -        |          |
| hasClear                | 是否显示清空按钮                                                         | boolean                                                                                                                                                           | true     |          |
| visible                 | 弹层显示状态                                                             | boolean                                                                                                                                                           | -        |          |
| defaultVisible          | 弹层默认是否显示                                                         | boolean                                                                                                                                                           | false    |          |
| onVisibleChange         | 弹层展示状态变化时的回调                                                 | (visible: boolean, reason: string) => void                                                                                                                        | -        |          |
| popupTriggerType        | 弹层触发方式                                                             | 'click' | 'hover'                                                                                                                                                | 'click'  |          |
| popupAlign              | 弹层对齐方式，具体含义见 OverLay 文档                                    | string                                                                                                                                                            | 'tl tl'  |          |
| popupContainer          | 弹层容器                                                                 | PopupProps\['container']                                                                                                                                           | -        |          |
| popupStyle              | 弹层自定义样式                                                           | React.CSSProperties                                                                                                                                               | -        |          |
| popupClassName          | 弹层自定义样式类                                                         | string                                                                                                                                                            | -        |          |
| popupProps              | 弹层其他属性                                                             | React.PropsWithRef\<PopupProps>                                                                                                                                   | -        |          |
| inputProps              | 输入框其他属性                                                           | InputProps                                                                                                                                                        | -        |          |
| dateCellRender          | 自定义日期渲染函数                                                       | () => void                                                                                                                                                        | -        |          |
| startDateInputAriaLabel | 开始日期输入框的 aria-label 属性                                         | string                                                                                                                                                            | -        |          |
| startTimeInputAriaLabel | 开始时间输入框的 aria-label 属性                                         | string                                                                                                                                                            | -        |          |
| endDateInputAriaLabel   | 结束日期输入框的 aria-label 属性                                         | string                                                                                                                                                            | -        |          |
| endTimeInputAriaLabel   | 结束时间输入框的 aria-label 属性                                         | string                                                                                                                                                            | -        |          |
| renderPreview           | 预览态定制渲染函数                                                       | (<br/> value: \[Moment | null, Moment | null],<br/> props: RangePickerProps<br/> ) => React.ReactNode                                                            | -        |          |
| onVisibleMonthChange    | 展现的月份变化时的回调                                                   | RangeCalendarProps\['onVisibleMonthChange']                                                                                                                        | -        |          |
| popupComponent          | 自定义弹层                                                               | React.ComponentType\<unknown>                                                                                                                                     | -        |          |
| popupContent            | 自定义弹层内容                                                           | React.ReactElement                                                                                                                                                | -        |          |
| monthCellRender         | 自定义月份渲染函数                                                       | (calendarDate: Moment) => React.ReactNode                                                                                                                         | -        |          |
| yearCellRender          | 自定义年份渲染函数                                                       | (calendarDate: Moment) => React.ReactNode                                                                                                                         | -        |          |
| followTrigger           | 是否跟随滚动                                                             | boolean                                                                                                                                                           | -        |          |
| isPreview               | 是否为预览态                                                             | boolean                                                                                                                                                           | -        |          |
| yearRange               | 年份范围，\[START\_YEAR, END\_YEAR]                                         | \[start: number, end: number]                                                                                                                                      | -        |          |
| disableChangeMode       | 禁用日期选择器的日期模式切换                                             | boolean                                                                                                                                                           | false    |          |

### DatePicker.YearPicker

| 参数               | 说明                                   | 类型                                                               | 默认值   | 是否必填 |
| ------------------ | -------------------------------------- | ------------------------------------------------------------------ | -------- | -------- |
| label              | 输入框内置标签                         | React.ReactNode                                                    | -        |          |
| state              | 输入框状态                             | 'success' | 'loading' | 'error'                                  | -        |          |
| placeholder        | 输入提示                               | string                                                             | -        |          |
| value              | 日期值（受控）moment 对象              | string | Moment | null                                           | -        |          |
| defaultValue       | 初始日期值，moment 对象                | string | Moment | null                                           | -        |          |
| format             | 日期值的格式（用于限定用户输入和展示） | string                                                             | 'YYYY'   |          |
| disabledDate       | 禁用日期函数                           | (date: Moment, view: string) => boolean                            | -        |          |
| footerRender       | 自定义面板页脚                         | () => React.ReactNode                                              | -        |          |
| onChange           | 日期值改变时的回调                     | (value: Moment | string | null) => void                          | -        |          |
| size               | 输入框尺寸                             | 'small' | 'medium' | 'large'                                     | 'medium' |          |
| disabled           | 是否禁用                               | boolean                                                            | -        |          |
| hasClear           | 是否显示清空按钮                       | boolean                                                            | true     |          |
| visible            | 弹层显示状态                           | boolean                                                            | -        |          |
| defaultVisible     | 弹层默认是否显示                       | boolean                                                            | -        |          |
| onVisibleChange    | 弹层展示状态变化时的回调               | (visible: boolean, reason: string) => void                         | -        |          |
| popupTriggerType   | 弹层触发方式                           | 'click' | 'hover'                                                 | 'click'  |          |
| popupAlign         | 弹层对齐方式，具体含义见 OverLay 文档  | string                                                             | 'tl tl'  |          |
| popupContainer     | 弹层容器                               | PopupProps\['container']                                            | -        |          |
| popupStyle         | 弹层自定义样式                         | React.CSSProperties                                                | -        |          |
| popupClassName     | 弹层自定义样式类                       | string                                                             | -        |          |
| popupProps         | 弹层其他属性                           | React.PropsWithRef\<PopupProps>                                    | -        |          |
| inputProps         | 输入框其他属性                         | InputProps                                                         | -        |          |
| dateInputAriaLabel | 日期输入框的 aria-label 属性           | string                                                             | -        |          |
| renderPreview      | 预览态定制渲染函数                     | (value: Moment | null, props: DatePickerProps) => React.ReactNode | -        |          |
| popupComponent     | 自定义弹层                             | React.ComponentType\<unknown>                                      | -        |          |
| popupContent       | 自定义弹层内容                         | React.ReactElement                                                 | -        |          |
| followTrigger      | 是否跟随滚动                           | boolean                                                            | -        |          |
| yearCellRender     | 自定义年份渲染函数                     | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| isPreview          | 是否为预览态                           | boolean                                                            | -        |          |

### DatePicker.WeekPicker

| 参数                 | 说明                                   | 类型                                                               | 默认值   | 是否必填 |
| -------------------- | -------------------------------------- | ------------------------------------------------------------------ | -------- | -------- |
| value                | 日期值（受控）moment 对象              | string | Moment | null                                           | -        |          |
| defaultValue         | 初始日期值，moment 对象                | string | Moment | null                                           | -        |          |
| visible              | 弹层显示状态                           | boolean                                                            | -        |          |
| defaultVisible       | 弹层默认是否显示                       | boolean                                                            | -        |          |
| format               | 日期值的格式（用于限定用户输入和展示） | string                                                             | 'GGGG    |          |
| onChange             | 日期值改变时的回调                     | (value: Moment | string | null) => void                          | -        |          |
| onVisibleChange      | 弹层展示状态变化时的回调               | (visible: boolean, reason: string) => void                         | -        |          |
| renderPreview        | 预览态定制渲染函数                     | (value: Moment | null, props: DatePickerProps) => React.ReactNode | -        |          |
| dateCellRender       | 自定义日期渲染函数                     | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| label                | 输入框内置标签                         | React.ReactNode                                                    | -        |          |
| state                | 输入框状态                             | 'success' | 'loading' | 'error'                                  | -        |          |
| defaultVisibleMonth  | 默认展现的月                           | () => Moment                                                       | false    |          |
| onVisibleMonthChange | 弹层展示月份变化时的回调               | (value: Moment, reason: string) => void                            | -        |          |
| disabledDate         | 禁用日期函数                           | (date: Moment, view: string) => boolean                            | -        |          |
| footerRender         | 自定义面板页脚                         | () => React.ReactNode                                              | -        |          |
| size                 | 输入框尺寸                             | 'small' | 'medium' | 'large'                                     | 'medium' |          |
| disabled             | 是否禁用                               | boolean                                                            | -        |          |
| hasClear             | 是否显示清空按钮                       | boolean                                                            | true     |          |
| popupTriggerType     | 弹层触发方式                           | 'click' | 'hover'                                                 | 'click'  |          |
| popupAlign           | 弹层对齐方式，具体含义见 OverLay 文档  | string                                                             | 'tl tl'  |          |
| popupContainer       | 弹层容器                               | PopupProps\['container']                                            | -        |          |
| popupStyle           | 弹层自定义样式                         | React.CSSProperties                                                | -        |          |
| popupClassName       | 弹层自定义样式类                       | string                                                             | -        |          |
| popupProps           | 弹层其他属性                           | React.PropsWithRef\<PopupProps>                                    | -        |          |
| popupComponent       | 自定义弹层                             | React.ComponentType\<unknown>                                      | -        |          |
| popupContent         | 自定义弹层内容                         | React.ReactElement                                                 | -        |          |
| followTrigger        | 是否跟随滚动                           | boolean                                                            | -        |          |
| inputProps           | 输入框其他属性                         | InputProps                                                         | -        |          |
| monthCellRender      | 自定义月份渲染函数                     | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| yearCellRender       | 自定义年份渲染函数                     | (calendarDate: Moment) => React.ReactNode                          | -        |          |
| isPreview            | 是否为预览态                           | boolean                                                            | -        |          |