|
| 1 | +# DateTimePicker control |
| 2 | + |
| 3 | +This control allows you to select dates from a calendar and optionally the time of day using dropdown controls. You can configure the control to use 12 or 24-hour clock. |
| 4 | + |
| 5 | +Here are some examples of the control: |
| 6 | + |
| 7 | +**DateTime Picker 12-hour clock** |
| 8 | + |
| 9 | + |
| 10 | +**DateTime Picker 24-hour clock** |
| 11 | + |
| 12 | + |
| 13 | +**DateTime Picker Date Only** |
| 14 | + |
| 15 | + |
| 16 | +## How to use this control in your solutions |
| 17 | + |
| 18 | +- Check that you installed the `@pnp/spfx-controls-react` dependency. Check out the [getting started](../#getting-started) page for more information about installing the dependency. |
| 19 | +- Import the control into your component. The DateConvention and TimeConvention controls if the time of day controls are shown and the time format used (12 hours/24 hours). |
| 20 | + |
| 21 | +```TypeScript |
| 22 | +import { DateTimePicker, DateConvention, TimeConvention } from '@pnp/spfx-controls-react/lib/dateTimePicker'; |
| 23 | +``` |
| 24 | +- Use the `DateTimePicker` control in your code as follows, either as an uncontrolled or a controlled component: |
| 25 | + |
| 26 | +```TypeScript |
| 27 | +// Uncontrolled |
| 28 | +<DateTimePicker label="DateTime Picker - 12h" |
| 29 | + dateConvention={DateConvention.DateTime} |
| 30 | + timeConvention={TimeConvention.Hours12} /> |
| 31 | + |
| 32 | +// Controlled |
| 33 | +<DateTimePicker label="DateTime Picker - 24h" |
| 34 | + dateConvention={DateConvention.DateTime} |
| 35 | + timeConvention={TimeConvention.Hours24} |
| 36 | + value={this.state.date} |
| 37 | + onChange={this.handleChange} /> |
| 38 | +``` |
| 39 | + |
| 40 | +## Implementation |
| 41 | + |
| 42 | +The `DateTimePicker` control can be configured with the following properties: |
| 43 | + |
| 44 | + |
| 45 | +| Property | Type | Required | Description | |
| 46 | +| ---- | ---- | ---- | ---- | |
| 47 | +| label | string | no | Property field label displayed on top. | |
| 48 | +| disabled | boolean | no | Specifies if the control is disabled or not. | |
| 49 | +| formatDate | function | no | Defines a formatDate function that can override the output value in Date picker. | |
| 50 | +| dateConvention | DateConvention | no | Defines the date convention to use. The default is date and time.| |
| 51 | +| timeConvention | TimeConvention | no | Defines the time convention to use. The default value is the 24-hour clock convention. | |
| 52 | +| firstDayOfWeek | DayOfWeek | no | Specify the first day of the week for your locale. | |
| 53 | +| key | string | no | A unique key that indicates the identity of this control | |
| 54 | +| onGetErrorMessage | function | no | The method is used to get the validation error message and determine whether the input value is valid or not. See [this documentation](https://dev.office.com/sharepoint/docs/spfx/web-parts/guidance/validate-web-part-property-values) to learn how to use it. | |
| 55 | +| showGoToToday | boolean | no | Controls whether the "Go to today" link should be shown or not | |
| 56 | +| isMonthPickerVisible | boolean | no | Controls whether the month picker is shown beside the day picker or hidden. | |
| 57 | +| showMonthPickerAsOverlay | boolean | no | Show month picker on top of date picker when visible. | |
| 58 | +| showWeekNumbers | boolean | no | Controls whether the calendar should show the week number (weeks 1 to 53) before each week row | |
| 59 | +| strings | IDatePickerStrings | no | Localized strings to use in the DateTimePicker | |
| 60 | +| value | Date | no | Default value of the DatePicker, if any | |
| 61 | +| onChange | function | no | Callback issued when date or time is changed | |
| 62 | +| showSeconds | boolean | no | Specifies, if seconds dropdown should be shown, defaults to false. | |
| 63 | + |
| 64 | +Enum `DateConvention` |
| 65 | + |
| 66 | +| Name | Description | |
| 67 | +| ---- | ---- | |
| 68 | +| DateTime | Shows the date and time picker | |
| 69 | +| Date | Shows only the date picker | |
| 70 | + |
| 71 | +Enum `TimeConvention` |
| 72 | + |
| 73 | +| Name | Description | |
| 74 | +| ---- | ---- | |
| 75 | +| Hours12 | Specify the hours in 12-hours (AM / PM) time convention. | |
| 76 | +| Hours24 | Specify the hours in 24-hours time convention. | |
| 77 | + |
| 78 | +Interface `IDateTimePickerStrings` extends [IDatePickerStrings](https://developer.microsoft.com/en-us/fabric#/components/datepicker) |
| 79 | + |
| 80 | +| Property | Type | Required | Description | |
| 81 | +| ---- | ---- | ---- | ---- | |
| 82 | +| dateLabel | string | no | Label for the date selector. | |
| 83 | +| timeLabel | string | no | Label for the time of day selector. | |
| 84 | +| timeSeparator | string | no | Separator between time of day components (hours, minutes, seconds). | |
| 85 | +| amDesignator | string | no | Used as AM designator when 12-hour clock is used. | |
| 86 | +| pmDesignator | string | no | Used as PM designator when 12-hour clock is used. | |
| 87 | + |
| 88 | + |
0 commit comments