DateField - Платформа CUBA. Руководство по разработке приложений

3.5.2.1.12. DateField

Поле для отображения и ввода даты и времени. Представляет собой поле даты, внутри которого имеется кнопка с выпадающим календарем, а правее находится поле для ввода времени.

XML-имя компонента: dateField.

Для создания поля даты, связанного с данными, необходимо использовать атрибуты dataContainer и property:
```
<data>
    <instance id="orderDc"
              class="com.company.sales.entity.Order"
              view="_local">
        <loader/>
    </instance>
</data>
<layout>
    <dateField dataContainer="orderDc"
               property="date"/>
</layout>
```
Как видно из примера, в экране описывается источник данных orderDc для некоторой сущности Заказ (Order), имеющей атрибут date. В компоненте ввода даты в атрибуте dataContainer указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено в поле.
Если поле связано с атрибутом сущности, то оно автоматически принимает соответствующий вид:
- Если атрибут типа java.sql.Date или указана аннотация @Temporal(TemporalType.DATE), то поле времени не отображается. Формат даты определяется типом данных date и задается в главном пакете локализованных сообщений в ключе dateFormat.
- В противном случае отображается также поле времени с часами и минутами. Формат времени определяется типом данных time и задается в главном пакете локализованных сообщений в ключе timeFormat.

Если поле не связано с атрибутом сущности (то есть не указан контейнер данных и название атрибута), то можно указать тип данных с помощью атрибута datatype. В DateField используются следующие типы данных:
- date
- dateTime
- localDate
- localDateTime
- offsetDateTime

Изменить формат представления даты и времени можно с помощью атрибута dateFormat. Значением атрибута может быть либо сама строка формата, либо ключ в пакете сообщений (если значение начинается с msg://).

Формат задается по правилам класса SimpleDateFormat (http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html). Если в формате отсутствуют символы H или h, то поле времени не выводится.

<dateField dateFormat="MM/yy" caption="msg://monthOnlyDateField"/>

DateField в основном предназначен для быстрого ввода с клавиатуры путем заполнения маски. Поэтому компонент поддерживает только форматы с цифрами и разделителями. Сложные форматы с текстовым представлением дня недели или месяца не будут работать.

Диапазон доступных дат можно указать с помощью атрибутов rangeStart и rangeEnd. Если данные атрибуты установлены, все даты, выходящие за пределы диапазона, будут отключены. Значения доступных даты можно установить в XML в формате "yyyy-MM-dd", или программно с помощью соответствующих сеттеров.
```
<dateField id="dateField" rangeStart="2016-08-15" rangeEnd="2016-08-19"/>
```

Атрибут autofill, установленный в значение true, включает автоматическое заполнение значений месяца и года текущими значениями после ввода дня. Если автозаполнение отключено, значение даты сбрасывается при неполном вводе.

В случае, если автозаполнение включено и установлены атрибуты rangeStart или rangeEnd, значения этих атрибутов будут учитываться при заполнении даты.

Точность представления даты и времени можно определить с помощью атрибута resolution. Значение атрибута должно соответствовать перечислению DateField.Resolution − SEC, MIN, HOUR, DAY, MONTH, YEAR. По умолчанию - MIN, то есть до минут.

Если resolution="DAY" и не указан атрибут dateFormat, то в качестве формата будет взят формат, указанный в главном пакете сообщений с ключом dateFormat.

Если resolution="MIN" и не указан атрибут dateFormat, то в качестве формата будет взят формат, указанный в главном пакете сообщений с ключом dateTimeFormat.

Ниже показано определения поля для ввода даты с точностью до месяца.
```
<dateField resolution="MONTH" caption="msg://monthOnlyDateField"/>
```
Изменение значения поля DateField, так же, как и любого другого компонента, реализующего интерфейс Field, можно отслеживать с помощью слушателя ValueChangeListener. Источник события ValueChangeEvent можно отследить с помощью метода isUserOriginated().
Если для пользователя методом setTimeZone() задан часовой пояс, то DateField может преобразовывать значения типа timestamp между часовыми поясами сервера и пользователя. Если компонент привязан к атрибуту типа timestamp, часовой пояс автоматически берется из текущей пользовательской сессии. Если нет, то можно вызвать метод setTimeZone() в контроллере экрана, чтобы DateField выполнил необходимые преобразования.

В веб-клиенте с темой, основанной на Halo, к компоненту DateField можно применить заданный стиль borderless, чтобы удалить рамку и фон поля. Стили задаются в XML-дексрипторе или контроллере экрана с помощью атрибута stylename:
```
<dateField id="dateField"
           stylename="borderless"/>
```
Чтобы применить стиль программно, выберите константу класса HaloTheme с префиксом компонента DATEFIELD_:
```
dateField.setStyleName(HaloTheme.DATEFIELD_BORDERLESS);
```

Атрибуты dateField: align - autofill - caption - captionAsHtml - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datatype - dateFormat - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - property - stylename - rangeEnd - rangeStart - required - requiredMessage - resolution - tabIndex - visible - width
Элементы dateField: validator
Предопределенные стили dateField: borderless - small - tiny
API: addValueChangeListener - commit - discard - isModified - setContextHelpIconClickHandler