DatePicker日期选择框

输入或选择日期的控件。

何时使用

当用户需要输入一个日期,可以点击标准输入框,弹出日期面板进行选择。

代码演示

DatePicker 日期选择框 - 图1

基本

最简单的用法,在浮层中可以选择或者输入日期。

  1. import { DatePicker } from 'antd';
  2. const { MonthPicker, RangePicker, WeekPicker } = DatePicker;
  3. function onChange(date, dateString) {
  4. console.log(date, dateString);
  5. }
  6. ReactDOM.render(
  7. <div>
  8. <DatePicker onChange={onChange} />
  9. <br />
  10. <MonthPicker onChange={onChange} placeholder="Select month" />
  11. <br />
  12. <RangePicker onChange={onChange} />
  13. <br />
  14. <WeekPicker onChange={onChange} placeholder="Select week" />
  15. </div>,
  16. mountNode,
  17. );

DatePicker 日期选择框 - 图2

三种大小

三种大小的输入框,若不设置,则为 default

  1. import { DatePicker, Radio } from 'antd';
  2. const { MonthPicker, RangePicker, WeekPicker } = DatePicker;
  3. class PickerSizesDemo extends React.Component {
  4. state = {
  5. size: 'default',
  6. };
  7. handleSizeChange = e => {
  8. this.setState({ size: e.target.value });
  9. };
  10. render() {
  11. const { size } = this.state;
  12. return (
  13. <div>
  14. <Radio.Group value={size} onChange={this.handleSizeChange}>
  15. <Radio.Button value="large">Large</Radio.Button>
  16. <Radio.Button value="default">Default</Radio.Button>
  17. <Radio.Button value="small">Small</Radio.Button>
  18. </Radio.Group>
  19. <br />
  20. <br />
  21. <DatePicker size={size} />
  22. <br />
  23. <MonthPicker size={size} placeholder="Select Month" />
  24. <br />
  25. <RangePicker size={size} />
  26. <br />
  27. <WeekPicker size={size} placeholder="Select Week" />
  28. </div>
  29. );
  30. }
  31. }
  32. ReactDOM.render(<PickerSizesDemo />, mountNode);

DatePicker 日期选择框 - 图3

禁用

选择框的不可用状态。

  1. import { DatePicker } from 'antd';
  2. import moment from 'moment';
  3. const { MonthPicker, RangePicker } = DatePicker;
  4. const dateFormat = 'YYYY-MM-DD';
  5. ReactDOM.render(
  6. <div>
  7. <DatePicker defaultValue={moment('2015-06-06', dateFormat)} disabled />
  8. <br />
  9. <MonthPicker defaultValue={moment('2015-06', 'YYYY-MM')} disabled />
  10. <br />
  11. <RangePicker
  12. defaultValue={[moment('2015-06-06', dateFormat), moment('2015-06-06', dateFormat)]}
  13. disabled
  14. />
  15. </div>,
  16. mountNode,
  17. );

DatePicker 日期选择框 - 图4

自定义日期范围选择

RangePicker 无法满足业务需求时,可以使用两个 DatePicker 实现类似的功能。

  • 通过设置 disabledDate 方法,来约束开始和结束日期。

  • 通过 open onOpenChange 来优化交互。

  1. import { DatePicker } from 'antd';
  2. class DateRange extends React.Component {
  3. state = {
  4. startValue: null,
  5. endValue: null,
  6. endOpen: false,
  7. };
  8. disabledStartDate = startValue => {
  9. const endValue = this.state.endValue;
  10. if (!startValue || !endValue) {
  11. return false;
  12. }
  13. return startValue.valueOf() > endValue.valueOf();
  14. };
  15. disabledEndDate = endValue => {
  16. const startValue = this.state.startValue;
  17. if (!endValue || !startValue) {
  18. return false;
  19. }
  20. return endValue.valueOf() <= startValue.valueOf();
  21. };
  22. onChange = (field, value) => {
  23. this.setState({
  24. [field]: value,
  25. });
  26. };
  27. onStartChange = value => {
  28. this.onChange('startValue', value);
  29. };
  30. onEndChange = value => {
  31. this.onChange('endValue', value);
  32. };
  33. handleStartOpenChange = open => {
  34. if (!open) {
  35. this.setState({ endOpen: true });
  36. }
  37. };
  38. handleEndOpenChange = open => {
  39. this.setState({ endOpen: open });
  40. };
  41. render() {
  42. const { startValue, endValue, endOpen } = this.state;
  43. return (
  44. <div>
  45. <DatePicker
  46. disabledDate={this.disabledStartDate}
  47. showTime
  48. format="YYYY-MM-DD HH:mm:ss"
  49. value={startValue}
  50. placeholder="Start"
  51. onChange={this.onStartChange}
  52. onOpenChange={this.handleStartOpenChange}
  53. />
  54. <DatePicker
  55. disabledDate={this.disabledEndDate}
  56. showTime
  57. format="YYYY-MM-DD HH:mm:ss"
  58. value={endValue}
  59. placeholder="End"
  60. onChange={this.onEndChange}
  61. open={endOpen}
  62. onOpenChange={this.handleEndOpenChange}
  63. />
  64. </div>
  65. );
  66. }
  67. }
  68. ReactDOM.render(<DateRange />, mountNode);

DatePicker 日期选择框 - 图5

额外的页脚

在浮层中加入额外的页脚,以满足某些定制信息的需求。

  1. import { DatePicker } from 'antd';
  2. const { RangePicker, MonthPicker } = DatePicker;
  3. ReactDOM.render(
  4. <div>
  5. <DatePicker renderExtraFooter={() => 'extra footer'} />
  6. <DatePicker renderExtraFooter={() => 'extra footer'} showTime />
  7. <RangePicker renderExtraFooter={() => 'extra footer'} />
  8. <RangePicker renderExtraFooter={() => 'extra footer'} showTime />
  9. <MonthPicker renderExtraFooter={() => 'extra footer'} placeholder="Select month" />
  10. </div>,
  11. mountNode,
  12. );

DatePicker 日期选择框 - 图6

定制日期单元格

使用 dateRender 可以自定义日期单元格的内容和样式。

  1. import { DatePicker } from 'antd';
  2. const { RangePicker } = DatePicker;
  3. ReactDOM.render(
  4. <div>
  5. <DatePicker
  6. dateRender={current => {
  7. const style = {};
  8. if (current.date() === 1) {
  9. style.border = '1px solid #1890ff';
  10. style.borderRadius = '50%';
  11. }
  12. return (
  13. <div className="ant-calendar-date" style={style}>
  14. {current.date()}
  15. </div>
  16. );
  17. }}
  18. />
  19. <RangePicker
  20. dateRender={current => {
  21. const style = {};
  22. if (current.date() === 1) {
  23. style.border = '1px solid #1890ff';
  24. style.borderRadius = '50%';
  25. }
  26. return (
  27. <div className="ant-calendar-date" style={style}>
  28. {current.date()}
  29. </div>
  30. );
  31. }}
  32. />
  33. </div>,
  34. mountNode,
  35. );

DatePicker 日期选择框 - 图7

日期格式

使用 format 属性,可以自定义日期显示格式。

  1. import { DatePicker } from 'antd';
  2. import moment from 'moment';
  3. const { MonthPicker, RangePicker } = DatePicker;
  4. const dateFormat = 'YYYY/MM/DD';
  5. const monthFormat = 'YYYY/MM';
  6. const dateFormatList = ['DD/MM/YYYY', 'DD/MM/YY'];
  7. ReactDOM.render(
  8. <div>
  9. <DatePicker defaultValue={moment('2015/01/01', dateFormat)} format={dateFormat} />
  10. <br />
  11. <DatePicker defaultValue={moment('01/01/2015', dateFormatList[0])} format={dateFormatList} />
  12. <br />
  13. <MonthPicker defaultValue={moment('2015/01', monthFormat)} format={monthFormat} />
  14. <br />
  15. <RangePicker
  16. defaultValue={[moment('2015/01/01', dateFormat), moment('2015/01/01', dateFormat)]}
  17. format={dateFormat}
  18. />
  19. </div>,
  20. mountNode,
  21. );

DatePicker 日期选择框 - 图8

日期时间选择

增加选择时间功能,当 showTime 为一个对象时,其属性会传递给内建的 TimePicker

  1. import { DatePicker } from 'antd';
  2. const { RangePicker } = DatePicker;
  3. function onChange(value, dateString) {
  4. console.log('Selected Time: ', value);
  5. console.log('Formatted Selected Time: ', dateString);
  6. }
  7. function onOk(value) {
  8. console.log('onOk: ', value);
  9. }
  10. ReactDOM.render(
  11. <div>
  12. <DatePicker showTime placeholder="Select Time" onChange={onChange} onOk={onOk} />
  13. <br />
  14. <RangePicker
  15. showTime={{ format: 'HH:mm' }}
  16. format="YYYY-MM-DD HH:mm"
  17. placeholder={['Start Time', 'End Time']}
  18. onChange={onChange}
  19. onOk={onOk}
  20. />
  21. </div>,
  22. mountNode,
  23. );

DatePicker 日期选择框 - 图9

不可选择日期和时间

可用 disabledDatedisabledTime 分别禁止选择部分日期和时间,其中 disabledTime 需要和 showTime 一起使用。

  1. import moment from 'moment';
  2. import { DatePicker } from 'antd';
  3. const { MonthPicker, RangePicker } = DatePicker;
  4. function range(start, end) {
  5. const result = [];
  6. for (let i = start; i < end; i++) {
  7. result.push(i);
  8. }
  9. return result;
  10. }
  11. function disabledDate(current) {
  12. // Can not select days before today and today
  13. return current && current < moment().endOf('day');
  14. }
  15. function disabledDateTime() {
  16. return {
  17. disabledHours: () => range(0, 24).splice(4, 20),
  18. disabledMinutes: () => range(30, 60),
  19. disabledSeconds: () => [55, 56],
  20. };
  21. }
  22. function disabledRangeTime(_, type) {
  23. if (type === 'start') {
  24. return {
  25. disabledHours: () => range(0, 60).splice(4, 20),
  26. disabledMinutes: () => range(30, 60),
  27. disabledSeconds: () => [55, 56],
  28. };
  29. }
  30. return {
  31. disabledHours: () => range(0, 60).splice(20, 4),
  32. disabledMinutes: () => range(0, 31),
  33. disabledSeconds: () => [55, 56],
  34. };
  35. }
  36. ReactDOM.render(
  37. <div>
  38. <DatePicker
  39. format="YYYY-MM-DD HH:mm:ss"
  40. disabledDate={disabledDate}
  41. disabledTime={disabledDateTime}
  42. showTime={{ defaultValue: moment('00:00:00', 'HH:mm:ss') }}
  43. />
  44. <br />
  45. <MonthPicker disabledDate={disabledDate} placeholder="Select month" />
  46. <br />
  47. <RangePicker
  48. disabledDate={disabledDate}
  49. disabledTime={disabledRangeTime}
  50. showTime={{
  51. hideDisabledOptions: true,
  52. defaultValue: [moment('00:00:00', 'HH:mm:ss'), moment('11:59:59', 'HH:mm:ss')],
  53. }}
  54. format="YYYY-MM-DD HH:mm:ss"
  55. />
  56. </div>,
  57. mountNode,
  58. );

DatePicker 日期选择框 - 图10

预设范围

可以预设常用的日期范围以提高用户体验。

  1. import { DatePicker } from 'antd';
  2. import moment from 'moment';
  3. const RangePicker = DatePicker.RangePicker;
  4. function onChange(dates, dateStrings) {
  5. console.log('From: ', dates[0], ', to: ', dates[1]);
  6. console.log('From: ', dateStrings[0], ', to: ', dateStrings[1]);
  7. }
  8. ReactDOM.render(
  9. <div>
  10. <RangePicker
  11. ranges={{
  12. Today: [moment(), moment()],
  13. 'This Month': [moment().startOf('month'), moment().endOf('month')],
  14. }}
  15. onChange={onChange}
  16. />
  17. <br />
  18. <RangePicker
  19. ranges={{
  20. Today: [moment(), moment()],
  21. 'This Month': [moment().startOf('month'), moment().endOf('month')],
  22. }}
  23. showTime
  24. format="YYYY/MM/DD HH:mm:ss"
  25. onChange={onChange}
  26. />
  27. </div>,
  28. mountNode,
  29. );

DatePicker 日期选择框 - 图11

受控面板

通过组合 modeonPanelChange 控制要展示的面板。

  1. import { DatePicker } from 'antd';
  2. const { RangePicker } = DatePicker;
  3. class ControlledDatePicker extends React.Component {
  4. state = { mode: 'time' };
  5. handleOpenChange = open => {
  6. if (open) {
  7. this.setState({ mode: 'time' });
  8. }
  9. };
  10. handlePanelChange = (value, mode) => {
  11. this.setState({ mode });
  12. };
  13. render() {
  14. return (
  15. <DatePicker
  16. mode={this.state.mode}
  17. showTime
  18. onOpenChange={this.handleOpenChange}
  19. onPanelChange={this.handlePanelChange}
  20. />
  21. );
  22. }
  23. }
  24. class ControlledRangePicker extends React.Component {
  25. state = {
  26. mode: ['month', 'month'],
  27. value: [],
  28. };
  29. handlePanelChange = (value, mode) => {
  30. this.setState({
  31. value,
  32. mode: [mode[0] === 'date' ? 'month' : mode[0], mode[1] === 'date' ? 'month' : mode[1]],
  33. });
  34. };
  35. handleChange = value => {
  36. this.setState({ value });
  37. };
  38. render() {
  39. const { value, mode } = this.state;
  40. return (
  41. <RangePicker
  42. placeholder={['Start month', 'End month']}
  43. format="YYYY-MM"
  44. value={value}
  45. mode={mode}
  46. onChange={this.handleChange}
  47. onPanelChange={this.handlePanelChange}
  48. />
  49. );
  50. }
  51. }
  52. ReactDOM.render(
  53. <div>
  54. <ControlledDatePicker />
  55. <br />
  56. <ControlledRangePicker />
  57. </div>,
  58. mountNode,
  59. );

API

日期类组件包括以下四种形式。

  • DatePicker

  • MonthPicker

  • RangePicker

  • WeekPicker

国际化配置

默认配置为 en-US,如果你需要设置其他语言,推荐在入口处使用我们提供的国际化组件,详见:LocaleProvider 国际化

如有特殊需求(仅修改单一组件的语言),请使用 locale 参数,参考:默认配置

  1. import locale from 'antd/lib/date-picker/locale/zh_CN';
  2. <DatePicker locale={locale} />;

注意:DatePicker、MonthPicker、RangePicker、WeekPicker 部分 locale 是从 value 中读取,所以请先正确设置 moment 的 locale。

  1. // 默认语言为 en-US,如果你需要设置其他语言,推荐在入口文件全局设置 locale
  2. import moment from 'moment';
  3. import 'moment/locale/zh-cn';
  4. moment.locale('zh-cn');
  5. <DatePicker defaultValue={moment('2015-01-01', 'YYYY-MM-DD')} />;

共同的 API

以下 API 为 DatePicker、MonthPicker、RangePicker, WeekPicker 共享的 API。

参数说明类型默认值
allowClear是否显示清除按钮booleantrue
autoFocus自动获取焦点booleanfalse
className选择器 classNamestring''
dateRender自定义日期单元格的内容function(currentDate: moment, today: moment) => React.ReactNode-
disabled禁用booleanfalse
disabledDate不可选择的日期(currentDate: moment) => boolean
dropdownClassName额外的弹出日历 classNamestring-
getCalendarContainer定义浮层的容器,默认为 body 上新建 divfunction(trigger)
locale国际化配置object默认配置
open控制弹层是否展开boolean-
placeholder输入框提示文字string|RangePicker[]-
popupStyle额外的弹出日历样式object{}
size输入框大小,large 高度为 40px,small 为 24px,默认是 32pxstring
suffixIcon自定义的选择框后缀图标ReactNode-
style自定义输入框样式object{}
onOpenChange弹出日历和关闭日历的回调function(status)
onPanelChange日历面板切换的回调function(value, mode)-

共同的方法

名称描述
blur()移除焦点
focus()获取焦点

DatePicker

参数说明类型默认值
defaultValue默认日期,如果开始时间或结束时间为 null 或者 undefined,日期范围将是一个开区间moment
defaultPickerValue默认面板日期moment
disabledTime不可选择的时间function(date)
format设置日期格式,为数组时支持多格式匹配,展示以第一个为准。配置参考 moment.jsstring | string[]"YYYY-MM-DD"
mode日期面板的状态time|date|month|year|decade'date'
renderExtraFooter在面板中添加额外的页脚(mode) => React.ReactNode-
showTime增加时间选择功能Object|booleanTimePicker Options
showTime.defaultValue设置用户选择日期时默认的时分秒,例子momentmoment()
showToday是否展示“今天”按钮booleantrue
value日期moment
onChange时间发生变化的回调function(date: moment, dateString: string)
onOk点击确定按钮的回调function()-
onPanelChange日期面板变化时的回调function(value, mode)-

MonthPicker

参数说明类型默认值
defaultValue默认日期moment
defaultPickerValue默认面板日期moment
format展示的日期格式,配置参考 moment.jsstring"YYYY-MM"
monthCellContentRender自定义的月份内容渲染方法function(date, locale): ReactNode-
renderExtraFooter在面板中添加额外的页脚() => React.ReactNode-
value日期moment
onChange时间发生变化的回调,发生在用户选择时间时function(date: moment, dateString: string)-

WeekPicker

参数说明类型默认值
defaultValue默认日期moment-
defaultPickerValue默认面板日期moment
format展示的日期格式,配置参考 moment.jsstring"YYYY-wo"
value日期moment-
onChange时间发生变化的回调,发生在用户选择时间时function(date: moment, dateString: string)-
renderExtraFooter在面板中添加额外的页脚(mode) => React.ReactNode-

RangePicker

参数说明类型默认值版本
defaultValue默认日期moment[]
defaultPickerValue默认面板日期moment[]
disabledTime不可选择的时间function(dates: [moment, moment], partial: 'start'|'end')
format展示的日期格式string"YYYY-MM-DD HH:mm:ss"
ranges预设时间范围快捷选择{ [range: string]: moment[] } | { [range: string]: () => moment[] }
renderExtraFooter在面板中添加额外的页脚() => React.ReactNode-
separator设置分隔符string'~'3.14.0
showTime增加时间选择功能Object|booleanTimePicker Options
showTime.defaultValue设置用户选择日期时默认的时分秒,例子moment[][moment(), moment()]
value日期moment[]
onCalendarChange待选日期发生变化的回调function(dates: [moment, moment], dateStrings: [string, string])
onChange日期范围发生变化的回调function(dates: [moment, moment], dateStrings: [string, string])
onOk点击确定按钮的回调function(dates: moment[])-