Enables the users to select date (between 0001-01-01 and 9999-12-31) and time values in a combined input.
The DateTimePicker
control consists of two parts: the input field and the date/time picker.
Note: The application developer should add dependency to sap.ui.unified
library on application level to ensure that the library is loaded before the module dependencies will be required. The sap.ui.unified.Calendar is used internally only if the DateTimePicker
is opened (not used for the initial rendering). If the sap.ui.unified
library is not loaded before the DateTimePicker
is opened, it will be loaded upon opening. This could lead to CSP compliance issues and adds an additional waiting time when the DateTimePicker
is opened for the first time. To prevent this, apps using the DateTimePicker
should also load the sap.ui.unified
library in advance.
Use this control if you need a combined date and time input control.
Don't use it if you want to use either a date or a time value. In this case, use the sap.m.DatePicker or the sap.m.TimePicker controls instead.
The user can enter a date by:
On app level, there are two options to provide a date for the DateTimePicker
- as a string to the value
property or as a JavaScript Date object to the dateValue
property (only one of these properties should be used at a time):
value
property if you want to bind the DateTimePicker
to a model using the sap.ui.model.type.DateTime
value
property if the date is provided as a string from the backend or inside the app (for example, as ABAP type DATS field)dateValue
property if the date is already provided as a JavaScript Date object or you want to work with a JavaScript Date object. Use dateValue
as a helper property to easily obtain the day, month, year, hours, minutes and seconds of the chosen date and time. Although possible to bind it, the recommendation is not to do it. When binding is needed, use value
property insteadAll formatting and parsing of dates from and to strings is done using the sap.ui.core.format.DateFormat. If a date is entered by typing it into the input field, it must fit to the used date format and locale.
Supported format options are pattern-based on Unicode LDML Date Format notation. See http://unicode.org/reports/tr35/#Date_Field_Symbol_Table
For example, if the valueFormat
is "yyyy-MM-dd-HH-mm-ss", the displayFormat
is "MMM d, y, HH:mm:ss", and the used locale is English, a valid value string is "2015-07-30-10-30-15", which leads to an output of "Jul 30, 2015, 10:30:15".
If no placeholder is set to the DateTimePicker
, the used displayFormat
is displayed as a placeholder. If another placeholder is needed, it must be set.
Note: If the string does NOT match the displayFormat
(from user input) or the valueFormat
(on app level), the sap.ui.core.format.DateFormat makes an attempt to parse it based on the locale settings. For more information, see the respective documentation in the API Reference.
The DateTimePicker
is responsive and fully adapts to all devices. For larger screens, such as tablet or desktop, it opens as a popover. For mobile devices, it opens in full screen.
Constructor for a new DateTimePicker
.
Accepts an object literal mSettings
that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.
new sap.m.DateTimePicker(sId?, mSettings?)
Param | Type | Default Value | Description |
---|---|---|---|
sId? | string | ID for the new control, generated automatically if no ID is given |
|
mSettings? | object | Initial settings for the new control |
Name | Type | Default Value | Description |
---|---|---|---|
minutesStep | int | 1 | Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step. |
secondsStep | int | 1 | Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step. |
Name | Type | Default Value | Description |
---|---|---|---|
displayFormatType | string | empty string | Displays date in this given type in input field. Default value is taken from locale settings. Accepted are values of |
maxDate | object | Maximum date that can be shown and selected in the Note: If the |
|
minDate | object | Minimum date that can be shown and selected in the Note: If the |
|
secondaryCalendarType | sap.ui.core.CalendarType | If set, the days in the calendar popup are also displayed in this calendar type If not set, the dates are only displayed in the primary calendar type |
|
showCurrentDateButton | boolean | false | Determines whether there is a shortcut navigation to Today. When used in Month, Year or Year-range picker view, the calendar navigates to Day picker view. Note: The Current date button appears if the |
showFooter | boolean | false | Hides or shows the popover's footer. |
dateValue | object | Holds a reference to a JavaScript Date Object. The |
|
displayFormat | string | Determines the format, displayed in the input field. Visibility: public |
|
initialFocusedDateValue | object | Holds a reference to a JavaScript Date Object to define the initially focused date/time when the picker popup is opened. Notes:
Since: 1.54.Visibility: public |
|
valueFormat | string | Determines the format of the value property. Visibility: public |
|
editable | boolean | true | Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it. |
enabled | boolean | true | Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain. Visibility: public |
name | string | The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission). Visibility: public |
|
placeholder | string | Defines a short hint intended to aid the user with data entry when the control has no value. Visibility: public |
|
required | boolean | false | Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation |
showValueStateMessage | boolean | true | Indicates whether the value state message should be shown or not. |
textAlign | sap.ui.core.TextAlign | Initial | Defines the horizontal alignment of the text that is shown inside the input field. |
textDirection | sap.ui.core.TextDirection | Inherit | Defines the text directionality of the input field, e.g. |
value | string | Defines the value of the control. Visibility: public |
|
valueState | sap.ui.core.ValueState | None | Visualizes the validation state of the control, e.g. |
valueStateText | string | Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle. |
|
width | sap.ui.core.CSSSize | Defines the width of the control. Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned. Visibility: public |
Name | Cardinality | Type | Description |
---|---|---|---|
specialDates | 0..n | sap.ui.core.Element |
Date Range with type to visualize special days in the Calendar. If one day is assigned to more than one Type, only the first one will be used. To set a single date (instead of a range), set only the startDate property of the sap.ui.unified.DateRange class. Note: Since 1.48 you could set a non-working day via the sap.ui.unified.CalendarDayType.NonWorking enum type just as any other special date type using sap.ui.unified.DateRangeType. |
formattedValueStateText | 0..1 | sap.m.FormattedText |
Defines the formatted text that appears in the value state message pop-up. It can include links. If both |
Method | Description |
---|---|
sap.m.DateTimePicker.extend |
Creates a new subclass of class sap.m.DateTimePicker with name
|
getAccessibilityInfo |
References:
|
getIconSrc |
Apply the correct icon to the used Date control |
sap.m.DateTimePicker.getMetadata |
Returns a metadata object for class sap.m.DateTimePicker. |
getMinutesStep |
Gets current value of property minutesStep. Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step. Default value is |
getSecondsStep |
Gets current value of property secondsStep. Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step. Default value is |
setMinutesStep |
Sets a new value for property minutesStep. Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step. When called with a value of Default value is |
setSecondsStep |
Sets a new value for property secondsStep. Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step. When called with a value of Default value is |
Creates a new subclass of class sap.m.DateTimePicker with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.m.DatePicker.extend.
Param | Type | DefaultValue | Description |
---|---|---|---|
sClassName | string |
Name of the class being created |
|
oClassInfo | object |
Object literal with information about the class |
|
FNMetaImpl | function |
Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class |
Gets current value of property minutesStep.
Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.
Default value is 1
.
Gets current value of property secondsStep.
Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.
Default value is 1
.
Sets a new value for property minutesStep.
Sets the minutes slider step. If the step is less than 1, it will be automatically converted back to 1. The minutes slider is populated only by multiples of the step.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is 1
.
Param | Type | DefaultValue | Description |
---|---|---|---|
iMinutesStep | int | 1 |
New value for property |
Sets a new value for property secondsStep.
Sets the seconds slider step. If the step is less than 1, it will be automatically converted back to 1. The seconds slider is populated only by multiples of the step.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is 1
.
Param | Type | DefaultValue | Description |
---|---|---|---|
iSecondsStep | int | 1 |
New value for property |