3p-react-datetime 中文文档教程

Question

react-datetime

同一 React.js 组件中的日期和时间选择器。 它可以用作日期选择器、时间选择器或同时用作两者。 它高度可定制，甚至允许编辑日期的毫秒数。

回归本源！ 感谢 YouCanBook.me（最佳日程安排工具） 的人们赞助 react-datetime长的。 现在该项目返回社区，我们正在寻找贡献者以继续改进 react-datetime。 你愿意帮忙吗？

第 3 版已经发布！ 这些是库第 3 版的文档。 如果您仍在使用已弃用的 v2，这是它的文档，但我们强烈建议迁移到版本 3 以继续接收更新。 请检查将 react-datetime 迁移到版本 3 以安全地更新您的应用。

Installation

使用 npm

npm install --save react-datetime

安装：使用 yarn 安装：

yarn add react-datetime

Usage

React.js 和 Moment.js 是 react-datetime 的对等依赖项（以及 Moment.js timezones 如果你想使用 < code>displayTimeZone 属性）。 这些依赖项不会与 react-datetime 一起自动安装，但您的项目需要安装它们才能使日期选择器工作。 然后，您可以像下面的示例一样使用日期选择器。

// Import the library
import Datetime from 'react-datetime';

// return it from your components
return <Datetime />;

查看此示例的运行情况。

你想要更多的例子吗？ 查看我们的资源库。

不要忘记添加 CSS 样式表它开箱即用。。 您只需要在您的应用程序中执行一次：

import "react-datetime/css/react-datetime.css";

API

下面我们提供了可以与 组件一起使用的所有道具。 还有一些方法可以命令式使用。

Name	Type	Default	Description
value	Date	new Date()	Represents the selected date by the component, in order to use it as a controlled component. This prop is parsed by Moment.js, so it is possible to use a date string or a moment object.
initialValue	Date	new Date()	Represents the selected date for the component to use it as a uncontrolled component. This prop is parsed by Moment.js, so it is possible to use a date string or a moment object. If you need to set the selected date programmatically after the picker is initialized, please use the value prop instead.
initialViewDate	Date	new Date()	Define the month/year/decade/time which is viewed on opening the calendar. This prop is parsed by Moment.js, so it is possible to use a date string or a moment object. If you want to set the view date after the component has been initialize see the imperative API.
initialViewMode	string or number	'days'	The default view to display when the picker is shown for the first time ('years', 'months', 'days', 'time'). If you want to set the view mode after the component has been initialize see the imperative API.
updateOnView	string	Intelligent guess	By default we can navigate through years and months without actualling updating the selected date. Only when we get to one view called the "updating view", we make a selection there and the value gets updated, triggering an onChange event. By default the updating view will get guessed by using the dateFormat so if our dates only show months and never days, the update is done in the months view. If we set updateOnView="time" selecting a day will navigate to the time view. The time view always updates the selected date, never navigates. If closeOnSelect={ true }, making a selection in the view defined by updateOnView will close the calendar.
dateFormat	boolean or string	true	Defines the format for the date. It accepts any Moment.js date format (not in localized format). If true the date will be displayed using the defaults for the current locale. If false the datepicker is disabled and the component can be used as timepicker, see available units docs.
timeFormat	boolean or string	true	Defines the format for the time. It accepts any Moment.js time format (not in localized format). If true the time will be displayed using the defaults for the current locale. If false the timepicker is disabled and the component can be used as datepicker, see available units docs.
input	boolean	true	Whether to show an input field to edit the date manually.
open	boolean	null	Whether to open or close the picker. If not set react-datetime will open the datepicker on input focus and close it on click outside.
locale	string	null	Manually set the locale for the react-datetime instance. Moment.js locale needs to be loaded to be used, see i18n docs.
utc	boolean	false	When true, input time values will be interpreted as UTC (Zulu time) by Moment.js. Otherwise they will default to the user's local timezone.
displayTimeZone	string	null	Needs moment's timezone available in your project. When specified, input time values will be displayed in the given time zone. Otherwise they will default to the user's local timezone (unless utc specified).
onChange	function	empty function	Callback trigger when the date changes. The callback receives the selected moment object as only parameter, if the date in the input is valid. If the date in the input is not valid, the callback receives the value of the input (a string).
onOpen	function	empty function	Callback trigger for when the user opens the datepicker.
onClose	function	empty function	Callback trigger for when the calendar get closed. The callback receives the selected moment object as only parameter, if the date in the input is valid. If the date in the input is not valid, the callback returns the value in the input.
onNavigate	function	empty function	Callback trigger when the view mode changes. The callback receives the selected view mode string (years, months, days or time) as only parameter.
onBeforeNavigate	function	( nextView, currentView, viewDate ) => nextView	Allows to intercept a change of the calendar view. The accepted function receives the view that it's supposed to navigate to, the view that is showing currently and the date currently shown in the view. Return a viewMode ( default ones are years, months, days or time) to navigate to it. If the function returns a "falsy" value, the navigation is stopped and we will remain in the current view.
onNavigateBack	function	empty function	Callback trigger when the user navigates to the previous month, year or decade. The callback receives the amount and type ('month', 'year') as parameters.
onNavigateForward	function	empty function	Callback trigger when the user navigates to the next month, year or decade. The callback receives the amount and type ('month', 'year') as parameters.
className	string or string array	''	Extra class name for the outermost markup element.
inputProps	object	undefined	Defines additional attributes for the input element of the component. For example: onClick, placeholder, disabled, required, name and className (className sets the class attribute for the input element). See Customize the Input Appearance.
isValidDate	function	() => true	Define the dates that can be selected. The function receives (currentDate, selectedDate) and shall return a true or false whether the currentDate is valid or not. See selectable dates.
renderInput	function	undefined	Replace the rendering of the input element. The function has the following arguments: the default calculated props for the input, openCalendar (a function which opens the calendar) and closeCalendar (a function which closes the calendar). Must return a React component or null. See Customize the Input Appearance.
renderView	function	(viewMode, renderDefault) => renderDefault()	Customize the way the calendar is rendered. The accepted function receives the type of the view it's going to be rendered 'years', 'months', 'days', 'time' and a function to render the default view of react-datetime, this way it's possible to wrap the original view adding our own markup or override it completely with our own code. See Customize the Datepicker Appearance.
renderDay	function	DOM.td(day)	Customize the way that the days are shown in the daypicker. The accepted function has the selectedDate, the current date and the default calculated props for the cell, and must return a React component. See Customize the Datepicker Appearance.
renderMonth	function	DOM.td(month)	Customize the way that the months are shown in the monthpicker. The accepted function has the selectedDate, the current date and the default calculated props for the cell, the month and the year to be shown, and must return a React component. See Customize the Datepicker Appearance.
renderYear	function	DOM.td(year)	Customize the way that the years are shown in the year picker. The accepted function has the selectedDate, the current date and the default calculated props for the cell, the year to be shown, and must return a React component. See Customize the Datepicker Appearance.
strictParsing	boolean	true	Whether to use Moment.js's strict parsing when parsing input.
closeOnSelect	boolean	false	When true, once the day has been selected, the datepicker will be automatically closed.
closeOnTab	boolean	true	When true and the input is focused, pressing the tab key will close the datepicker.
timeConstraints	object	null	Add some constraints to the timepicker. It accepts an object with the format { hours: { min: 9, max: 15, step: 2 }}, this example means the hours can't be lower than 9 and higher than 15, and it will change adding or subtracting 2 hours everytime the buttons are clicked. The constraints can be added to the hours, minutes, seconds and milliseconds.
closeOnClickOutside	boolean	true	When the calendar is open and closeOnClickOutside is true (its default value), clickin outside of the calendar or input closes the calendar. If false the calendar stays open.

Imperative API

除了控制所选日期之外，react-datetime 还为我们处理了几个月、几年、几十年的导航。 我们可以干预它，使用 onBeforeNavigate 属性停止视图转换，但我们也可以使用一些命令式方法导航到特定视图和日期。

为此，我们需要使用 ref 属性创建我们的组件并使用引用。

// This would be the code to render the picker
<DateTime ref="datetime" />

// ... once rendered we can use the imperative API
// let's show the years view
this.refs.datetime.navigate('years')

可用的方法有：

• navigate( viewMode ): Set the view currently shown by the calendar. View modes shipped with react-datetime are years, months, days and time, but you can alse navigate to custom modes that can be defined by using the renderView prop.
• setViewDate( date ): Set the date that is currently shown in the calendar. This is independent from the selected date and it's the one used to navigate through months or days in the calendar. It accepts a string in the format of the current locale, a Date or a Moment object as parameter.

i18n

react-datetime 支持不同的语言和日期格式。 React 使用 Moment.js 来格式化日期，更改日历语言的最简单方法是 更改 Moment.js 语言环境。

不要忘记从 moment 的 moment/locale 文件夹中导入您的语言环境文件。

import moment from 'moment';
import 'moment/locale/fr';
// Now react-datetime will be in french

如果加载了多个语言环境，您可以使用属性 locale 来定义实例应使用的语言。

<Datetime locale="fr-ca" />
<Datetime locale="de" />

在这里您可以看到正在运行的 i18n 示例。

Customize the Input Appearance

可以自定义输入的显示方式。 最简单的方法是提供 inputProps，它将直接分配给组件内的 元素。 我们可以通过这种方式调整输入：

let inputProps = {
    placeholder: 'N/A',
    disabled: true,
    onMouseLeave: () => alert('You went to the input but it was disabled')
};

<Datetime inputProps={ inputProps } />

查看自定义输入的工作情况

或者，如果您需要呈现与 元素不同的内容，您可以提供一个 renderInput 函数，该函数将被调用。

class MyDTPicker extends React.Component {
    render(){
        return <Datetime renderInput={ this.renderInput } />;
    }
    renderInput( props, openCalendar, closeCalendar ){
        function clear(){
            props.onChange({target: {value: ''}});
        }
        return (
            <div>
                <input {...props} />
                <button onClick={openCalendar}>open calendar</button>
                <button onClick={closeCalendar}>close calendar</button>
                <button onClick={clear}>clear</button>
            </div>
        );
    }
}

查看此示例的运行情况

或者您可能只想显示日历而根本不需要输入。 在这种情况下，input={ false } 会成功：

    <Datetime input={ false } />;

请参阅 react-datetime calendar working without an input

Customize the Datepicker Appearance

可以自定义日期选择器在日历中显示日、月和年的方式。 为了适应每个需要的日历，可以使用道具 renderDay(props, currentDate, selectedDate), renderMonth(props, month, year, selectedDate) 和 renderYear(props, year, selectedDate) 自定义每个渲染方法的输出。

class MyDTPicker extends React.Component {
  render() {
    return (
      <Datetime
        renderDay={this.renderDay}
        renderMonth={this.renderMonth}
        renderYear={this.renderYear}
      />
    );
  }
  renderDay(props, currentDate, selectedDate) {
    // Adds 0 to the days in the days view
    return <td {...props}>{"0" + currentDate.date()}</td>;
  }
  renderMonth(props, month, year, selectedDate) {
    // Display the month index in the months view
    return <td {...props}>{month}</td>;
  }
  renderYear(props, year, selectedDate) {
    // Just display the last 2 digits of the year in the years view
    return <td {...props}>{year % 100}</td>;
  }
}

在此处查看自定义日历。

也可以完全覆盖日历中的某些视图。 假设我们想在我们的日历中添加一个今天按钮，当我们点击它时我们会转到今天视图：

class MyDTPicker extends React.Component {
  render() {
    return (
      <Datetime
        ref="datetime"
        renderView={(mode, renderDefault) =>
          this.renderView(mode, renderDefault)
        }
      />
    );
  }

  renderView(mode, renderDefault) {
    // Only for years, months and days view
    if (mode === "time") return renderDefault();

    return (
      <div className="wrapper">
        {renderDefault()}
        <div className="controls">
          <button onClick={() => this.goToToday()}>Today</button>
        </div>
      </div>
    );
  }

  goToToday() {
    // Reset
    this.refs.datetime.setViewDate(new Date());
    this.refs.datetime.navigate("days");
  }
}

看到它工作

Method Parameters

• props is the object that the datepicker has calculated for this object. It is convenient to use this object as the props for your custom component, since it knows how to handle the click event and its className attribute is used by the default styles.
• selectedDate and currentDate are moment objects and can be used to change the output depending on the selected date, or the date for the current day.
• month and year are the numeric representation of the current month and year to be displayed. Notice that the possible month values range from 0 to 11.

Make it work as a year picker or a time picker

您可以使用 dateFormat 和 timeFormat 过滤出您希望用户能够选择的内容，例如创建时间选择器、年份选择器等。

在此示例中该组件用作时间选择器，并且只能用于选择时间。

<Datetime dateFormat={false} />

此处为时间选择器的工作示例。

在此示例中，您只能选择年份和月份。

<Datetime dateFormat="YYYY-MM" timeFormat={false} />

此处仅选择年份和月份的工作示例。

Blocking some dates to be selected

如果用户不喜欢，则可以禁用日历中的日期允许选择它们，例如过去的日期。 这是使用 isValidDate 属性完成的，它接受 function(currentDate, selectedDate) 形式的函数，其中两个参数都是 时刻对象。 该函数应为可选日期返回 true，为禁用日期返回 false。

在下面的示例中，今天之前的所有日期 均已禁用。

import moment from 'moment';
var yesterday = moment().subtract( 1, 'day' );
var valid = function( current ){
    return current.isAfter( yesterday );
};
<Datetime isValidDate={ valid } />

此处禁用日的工作示例。

也可以禁用周末，如图所示在下面的例子中。

var valid = function( current ){
    return current.day() !== 0 && current.day() !== 6;
};
<Datetime isValidDate={ valid } />

此处禁用周末的工作示例。

Usage with TypeScript

该项目包括 TypeScript 版本 1.8 和 2.0 的类型。 额外的打字不是 必需的。

1.8 的类型可以在 react-datetime.d.ts 中找到，2.0 的类型可以在 typings/index.d.ts 中找到。

import * as Datetime from 'react-datetime';

class MyDTPicker extends React.Component<MyDTPickerProps, MyDTPickerState> {
    render() JSX.Element {
        return <Datetime />;
    }
}

Contributions

react-datetime 是由社区为社区制作的。 像你这样有兴趣贡献的人是项目的关键！ ？？？？？？？？？

查看我们的贡献页面，了解如何开始。

Changelog

MIT Licensed