DatePicker 日期选择框

如果项目中使用的是 0.x 版本的基础组件（@icedesign/base, @ali/ice, @alife/next），请在左侧导航顶部切换组件版本。

安装方法

在命令行中执行以下命令npm install @alifd/next@latest -S

Guide

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

日期选择模式

DatePicker/RangePicker 在交互上增加了操作焦点的设置，意味着，如果某个输入框处于 focus 态，那么当前选择的日期将会作用于该输入框对应的日期。

如上图所示，带时间的 RangePicker 有 4 个输入焦点，分别为开始日期、开始时间、结束日期、结束时间。当用户激活某个输入框时，此时下拉选择的日期将会作用域该输入框。同时设置了如下两个规则：

• 已选定日期范围后，当焦点在开始日期时，如果即将选择的日期大于结束日期，将会重设开始日期。

• 已选定日期范围后，当焦点在结束日期时，如果即将选择的日期小于开始日期，将会重设开始日期。

日期值的多语言

由于 Calendar 组件内部使用 moment 对象来设置日期（请使用最新版 moment），部分 Locale 读取自 moment，因此用户需要在外部使用时正确的设置 moment 的 locale 。

• Q: 文档站点上看是中式日历，为什么我本地却是美式日历呢？如何进行多语言适配？A: 日期的多语言情况比较复杂，涉及到年、月、日、星期、阅读习惯等多方面(美式从周日到周六，中式从周一到周日)，因此我们借助了成熟的时间库 moment.js 来进行日期的多语言处理。 moment.js 默认支持美式表达，如需中文等其他语言，请引入moment-with-locales.js语言包。

import moment from 'moment';
moment.locale('zh-cn');

此外，当改变 moment 的全局 locale 时并不会修改之前的已有实例，例如：

moment.locale('fr');
const m = moment(1316116057189);
m.fromNow(); // il y a une heure
moment.locale('en');
m.fromNow(); // il y a une heure
moment(1316116057189).fromNow(); // an hour ago

除了全局设置 moment 的多语言，还可以只对某个 moment 实例设置多语言。比如：

const value = moment();
value.locale('fr'); // set this instance to use French

Moment 对象和字符串

DatePicker 默认情况下接收和返回的数据类型都是 Moment 对象。为了便于用户的使用，DatePikcer 还支持直接传入字符串（组件内部仍然会格式化为 Moment 对象）。使用方法如下：

标准非受控

<DatePicker onChange={val => console.log(val)} />
// select 2019-01-23
// >> MomentObject
<DatePicker defaultValue={moment()} onChange={val => console.log(val)} />
// select 2019-01-23
// >> MomentObject
<DatePicker defaultValue="2018-01-23" onChange={val => console.log(val)} />
// select 2019-01-23
// >> "2019-01-23"

标准受控

<DatePicker value={moment()} onChange={val => console.log(val)} />
// setProps({ value: moment().add(1, 'months') })
// >> MomentObject
<DatePicker value="2018-01-23" onChange={val => console.log(val)} />
// setProps({ value: '2019-01-23' })
// >> "2019-01-23"

API

DatePicker

DatePicker.MonthPicker

DatePicker.RangePicker

DatePicker.YearPicker

ARIA and KeyBoard

同选择框一样聚焦到 DatePiker 后，需要按下 ENTER 键打开弹出框，选择/输入日期， 通过 TAB 切换日期和时间输入框。

代码示例

基本用法

最基本的用法。可以通过 onChange 监听选中值的变化。

查看源码在线预览

import { DatePicker } from '@alifd/next';
const { RangePicker, MonthPicker, YearPicker } = DatePicker;
const onChange = val => console.log(val);
ReactDOM.render(<div>
    <DatePicker onChange={onChange} /> <br /><br />
    <MonthPicker onChange={onChange} /> <br /><br />
    <YearPicker onChange={onChange} /> <br /><br />
    <RangePicker onChange={onChange} />
</div>, mountNode);

提供默认值

可以通过 defaultValue 属性为日期选择器提供初值，所提供的初值必须为 moment 对象。

查看源码在线预览

import { DatePicker } from '@alifd/next';
import moment from 'moment';
const { RangePicker, MonthPicker, YearPicker } = DatePicker;
const startValue = moment('2017-11-20', 'YYYY-MM-DD', true);
const endValue = moment('2017-12-15', 'YYYY-MM-DD', true);
const onChange = val => console.log(val);
ReactDOM.render(<div>
    <DatePicker defaultValue={startValue} onChange={onChange} /><br /><br />
    <MonthPicker defaultValue={startValue} onChange={onChange} /><br /><br />
    <YearPicker defaultValue={startValue} onChange={onChange} /><br /><br />
    <RangePicker defaultValue={[startValue, endValue]} onChange={onChange} />
</div>, mountNode);

面板的默认展现日期

可以通过 defaultVisibleMonth 或 defaultVisibleYear 属性可以修改面板的默认展现日期。

查看源码在线预览

import { DatePicker } from '@alifd/next';
import moment from 'moment';
const { RangePicker, MonthPicker } = DatePicker;
function onVisibleMonthChange(val, reason) {
    console.log(val.format('L'), reason);
}
ReactDOM.render(<div>
    <p>Setting last month as default visible month</p>
    <DatePicker defaultVisibleMonth={() => moment().add(-1, 'months')} onVisibleMonthChange={onVisibleMonthChange} />
    <br /><br />
    <RangePicker defaultVisibleMonth={() => moment().add(-1, 'months')} onVisibleMonthChange={onVisibleMonthChange} />
    <br /><br />
    <p>Setting 2017 as default visible year</p>
    <MonthPicker defaultVisibleYear={() => moment('2017', 'YYYY')} />
</div>, mountNode);

不同尺寸

通过 size 属性可以改变 Input 组件的尺寸，默认为 medium。

查看源码在线预览

import { DatePicker } from '@alifd/next';
ReactDOM.render(<div>
    <DatePicker size="large" /> &nbsp;&nbsp;
    <DatePicker /> &nbsp;&nbsp;
    <DatePicker size="small" />
</div>, mountNode);

禁止选择某些日期

可以通过 disabledDate 属性来禁止用户选择或输入某些特定日期。

查看源码在线预览

import { DatePicker } from '@alifd/next';
import moment from 'moment';
const { RangePicker, MonthPicker, YearPicker } = DatePicker;
const currentDate = moment();
// Disable all dates before today
const disabledDate = function (date, view) {
    switch (view) {
        case 'date':
            return date.valueOf() <= currentDate.valueOf();
        case 'year':
            return date.year() < currentDate.year();
        case 'month':
            return date.year() * 100 + date.month() < currentDate.year() * 100 + currentDate.month();
        default: return false;
    }
};
ReactDOM.render(<div>
    <DatePicker disabledDate={disabledDate} onChange={val => console.log(val)} /><br /><br />
    <MonthPicker disabledDate={disabledDate} onChange={val => console.log(val)} /><br /><br />
    <YearPicker disabledDate={disabledDate} onChange={val => console.log(val)} /><br /><br />
    <RangePicker disabledDate={disabledDate} onChange={val => console.log(val)} />
</div>, mountNode);

日期时间选择

如果需要同时选择时间，可以通过 showTime 属性开启，showTime 支持传入 TimePickerPanel 的属性，例如 format, defaultValue 等。

查看源码在线预览

import { DatePicker } from '@alifd/next';
import moment from 'moment';
const { RangePicker } = DatePicker;
const onChange = (value) => console.log(value);
const onOk = (value) => console.log('onOK:', value.format('YYYY-MM-DD HH:mm:ss'));
const onRangeOk = (value) => console.log('onOk: [%s, %s]', value[0].format('YYYY-MM-DD HH:mm:ss'), value[1].format('YYYY-MM-DD HH:mm:ss'));
const defaultTimeValue = moment('09:00:00', 'HH:mm:ss', true);
ReactDOM.render(<div>
    <p>DatePicker With Time</p>
    <DatePicker showTime onChange={onChange} onOk={onOk} />
    <p>DatePicker with Time, reset 00:00:00 for every select</p>
    <DatePicker showTime onChange={onChange} onOk={onOk} resetTime />
    <p>DatePicker with Time, with default time value</p>
    <DatePicker showTime={{ defaultValue: defaultTimeValue, secondStep: 10 }} onChange={onChange} onOk={onOk} />
    <p>RangePicker with Time</p>
    <RangePicker showTime onChange={onChange} onOk={onRangeOk} />
    <p>RangePicker with Time, reset 00:00:00 for every select</p>
    <RangePicker showTime resetTime onChange={onChange} onOk={onRangeOk} />
    <p>RangePicker with Time, with default time value, hide seconds</p>
    <RangePicker showTime={{ defaultValue: defaultTimeValue, format: 'HH:mm', minuteStep: 15 }} onChange={onChange} onOk={onRangeOk} />
</div>, mountNode);

禁用日期选择

当开启 disabled 属性时，选择框处于完全禁用状态。

查看源码在线预览

import { DatePicker } from '@alifd/next';
const { RangePicker } = DatePicker;
ReactDOM.render(<div>
    <DatePicker disabled />&nbsp;&nbsp;<RangePicker disabled />
</div>, mountNode);

日期格式

通过 format 属性可以约束日期选择器的日期格式，该格式同时会限定用户的输入格式。

查看源码在线预览

import { DatePicker } from '@alifd/next';
const { RangePicker } = DatePicker;
const onChange = val => console.log(val);
ReactDOM.render(<div>
    <DatePicker format="YYYY-M-D" onChange={onChange} />
    <br /><br />
    <DatePicker format="YYYY-M-D" onChange={onChange} showTime={{ format: 'HH:mm' }} />
    <br /><br />
    <RangePicker format="YYYY-M-D" onChange={onChange} />
    <br /><br />
    <RangePicker format="YYYY-M-D" onChange={onChange} showTime={{ format: 'HH:mm' }} />
</div>, mountNode);

自定义日期范围选择

如果默认的 RangePicker 在交互上无法满足您的使用需求，还可以基于 DatePicker 封装实现类似的功能。例如，示例中的日期选择可以自由的更改开始或结束日期，而不必每次选择时重置日期。

查看源码在线预览

import { DatePicker } from '@alifd/next';
class CustomRangePicker extends React.Component {
    constructor(props, context) {
        super(props, context);
        this.state = {
            startValue: null,
            endValue: null,
            endOpen: false
        };
    }
    disabledStartDate = (startValue) => {
        const { endValue } = this.state;
        if (!startValue || !endValue) {
            return false;
        }
        return startValue.valueOf() > endValue.valueOf();
    }
    disabledEndDate = (endValue) => {
        const { startValue } = this.state;
        if (!endValue || !startValue) {
            return false;
        }
        return endValue.valueOf() <= startValue.valueOf();
    }
    onChange = (stateName, value) => {
        this.setState({
            [stateName]: value
        });
    }
    onStartChange = (value) => {
        this.onChange('startValue', value);
    }
    onEndChange = value => {
        this.onChange('endValue', value);
    }
    handleStartOpenChange = (open) => {
        if (!open) {
            this.setState({ endOpen: true });
        }
    }
    handleEndOpenChange = (open) => {
        this.setState({ endOpen: open });
    }
    render() {
        const { endOpen } = this.state;
        return (
            <div>
                <DatePicker
                    disabledDate={this.disabledStartDate}
                    placeholder="Departure Date"
                    onChange={this.onStartChange}
                    onVisibleChange={this.handleStartOpenChange}
                />
                <span className="custom-sep">-</span>
                <DatePicker
                    disabledDate={this.disabledEndDate}
                    placeholder="Return Date"
                    onChange={this.onEndChange}
                    visible={endOpen}
                    onVisibleChange={this.handleEndOpenChange}
                />
            </div>
        );
    }
}
ReactDOM.render(<div>
    <CustomRangePicker />
</div>, mountNode);

.custom-sep {
    margin: 0 6px;
    color: #999;
}

自定义日期选择器弹层

组件对外透出了 visible, defaultVisible, onVisibleChange, popupTriggerType, popupAlign, popupContainer, popupStyle, popupClassName 等属性用于直接定制弹层。此外，如果这些属性仍然无法满足需求，可以通过 popupProps 进行透传。

查看源码在线预览

import { DatePicker } from '@alifd/next';
const { RangePicker } = DatePicker;
ReactDOM.render(<div>
    <p>Change popup align</p>
    <DatePicker popupAlign="bl tl" />
    <p>Change popup container</p>
    <RangePicker popupContainer={target => target.parentNode} />
</div>, mountNode);

自定义面板页脚

可以通过 footerRender 自定义对面板页脚的定制。

查看源码在线预览

import { DatePicker } from '@alifd/next';
const { RangePicker } = DatePicker;
function footerRender() {
    return <div className="custom-footer">👍 Some useful info here</div>;
}
ReactDOM.render(<div>
    <DatePicker footerRender={footerRender} />&nbsp;&nbsp;
    <RangePicker footerRender={footerRender} />
</div>, mountNode);

.custom-footer {
    padding: 12px;
    font-size: 12px;
    border-top: 1px solid #DCDEE3;
}

与 Field 结合

与 Field 结合使用，简单示范自定义返回值

查看源码在线预览

import { DatePicker, Field, Button } from '@alifd/next';
const { RangePicker, YearPicker, MonthPicker } = DatePicker;
class App extends React.Component {
    field = new Field(this);
    printData = () => {
        this.field.validate((err, values) => {
            if (err) {
                console.error('Error: ', err);
                return;
            }
            console.log('datepicker: %s', values.date.format('YYYY-MM-DD'));
            console.log('monthpicker: %s', values.month.format('YYYY-MM'));
            console.log('yearpicker: %s', values.year.format('YYYY'));
            const range = values.range;
            console.log('rangepicker: [%s, %s]', range[0] && range[0].format('YYYY-MM-DD'), range[1] && range[1].format('YYYY-MM-DD'));
        });
    }
    printError = (name) => {
        if (this.field.getError(name)) {
            return <span className="error-msg">{this.field.getError(name).join(',')}</span>;
        }
    }
    render() {
        const init = this.field.init;
        return (
            <div>
                <DatePicker {...init('date', { rules: [{
                    required: true,
                    message: '请选择日期'
                }] })} />{this.printError('date')}<br /><br />
                <MonthPicker {...init('month', { rules: [{
                    required: true,
                    message: '请选择月份'
                }] })} />{this.printError('month')}<br /><br />
                <YearPicker {...init('year', { rules: [{
                    required: true,
                    message: '请选择年份'
                }] })} />{this.printError('year')}<br /><br />
                <RangePicker {...init('range', { rules: [{
                    required: true,
                    message: '请选择日期范围'
                }] })} />{this.printError('range')}<br /><br />
                <Button onClick={this.printData}>Print to Console</Button>
            </div>
        );
    }
}
ReactDOM.render(<App/>, mountNode);

.error-msg {
    color: #E72B00;
    font-size: 12px;
}

无障碍

支持手动输入或键盘操作，请参考ARIA and KeyBoard。

查看源码在线预览

import { DatePicker } from '@alifd/next';
const { RangePicker, MonthPicker, YearPicker } = DatePicker;
const onChange = val => console.log(val);
ReactDOM.render(<div>
    <DatePicker dateInputAriaLabel="date input" inputProps={{"aria-label": "date picker main"}}  onChange={onChange} /> <br /><br />
    <RangePicker startDateInputAriaLabel="start date" startTimeInputAriaLabel="start time" endDateInputAriaLabel="end date" endTimeInputAriaLabel="end time" onChange={onChange} inputProps={{"aria-label": "range picker main"}} />
</div>, mountNode);

相关区块

暂无相关区块