3.5.2.1.12. 日期时间组件

在线示例

API 文档

DateField 由日期控件和时间控件组成。日期控件是支持输入的控件，在输入框里面带有一个可以下拉选择日期的按钮，时间控件则在日期输入控件的右边：

gui dateFieldSimple

该组件对应的 XML 名称：dateField

  1. <data>
  2.     <instance id="orderDc"
  3.               class="com.company.sales.entity.Order"
  4.               view="_local">
  5.         <loader/>
  6.     </instance>
  7. </data>
  8. <layout>
  9.     <dateField dataContainer="orderDc"
  10.                property="date"/>
  11. </layout>

在上面这个例子中，界面有 Order 实体的数据容器 orderDc，Order 实体拥有 date 属性。XML 里面将 dateField 的 dataContainer 属性指向这个数据容器，然后将 property 属性指向实体中需要显示在这个控件的字段。

  • 如果这个控件关联实体的一个属性，它能根据实体属性的类型自动填充日期时间格式：

  • 如果这个实体属性是 java.sql.Date 类型或者这个属性有 @Temporal(TemporalType.DATE) 注解，那么时间控件部分会被隐藏不显示。日期控件部分的格式会按照 date 数据类型的格式显示，这个格式从主本地化消息包中的 dateFormat 键获取。

  • 其它情况下，时间控件会显示小时和分钟。时间部分的格式会按照 time 数据类型的格式显示，这个格式从主本地化消息包的 timeFormat 键获取。

  • 日期时间格式也可以通过组件的 dateFormat 属性来设置。这个属性的值可以是一个定义日期时间格式的字符串或者语言包中的一个键。

日期时间格式是使用 SimpleDateFormat 类提供的规则来定义。( http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html )。 如果格式中没有 H 或者 h 的话，时间控件部分将不显示。

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

gui dateField format

DateField 主要目的是通过填充占位符来使用键盘快速输入。所以这个组件只支持包含数字和分隔符的日期时间格式。那些复杂的含有星期文字表述或者月文字表述的格式目前是不支持的。

  • 可以通过 rangeStart 和 rangeEnd 属性来定义可选的日期范围。一旦日期范围设定了，其它在范围之外的日期都会变成不可选状态。日期范围可以用"yyyy-MM-dd"这样的格式在界面 XML 里面配置或者在程序里通过相应的 setter 来设置。
  1. <dateField id="dateField" rangeStart="2016-08-15" rangeEnd="2016-08-19"/>

gui datefield month range

  • DateField 组件值的变化，跟其它实现了 Field 接口的组件一样，都可以用 ValueChangeListener 来监听。可以使用isUserOriginated() 方法跟踪 ValueChangeEvent 的来源。
  • 日期和时间的精度可以用组件的 resolution 属性来定义，这个属性的值需要是 DateField.Resolution 枚举类型 - SEC 、MIN 、HOUR 、DAY 、 MONTH 、YEAR。默认精度是 MIN，精确到分钟。

如果 resolution="DAY" 而且 dateFormat 没有给定的话，控件的显示格式会从主本地化消息包里的 dateFormat 键获取。

如果 resolution="MIN" 而且 dateFormat 没有给定的话，控件的显示格式会从主本地化消息包里的 dateTimeFormat 键获取。下面这个例子是精确到月的日期时间组件的写法：

  1. <dateField resolution="MONTH" caption="msg://monthOnlyDateField"/>

gui dateField resolution

  • DateField 还可以在服务器和用户之间转换时间戳的时区，前提是用户通过 setTimeZone() 设置了时区。当这个组件绑定了一个实体里的时间戳类型的属性的时候，时区会通过当前的用户会话自动设定。如果组件没有绑定时间戳类型的属性，可以通过在界面控制器调用 setTimeZone() 手动设置时区，这样 DateField 可以自动进行时区转换。

  • 日历中的当前日期是根据用户浏览器的时间戳确定的，依赖操作系统时区的设置。用户会话的时区不会影响此功能。

  • 在选用 Halo-based 主题的 Web Client，如果需要无边框无背景的样式，可以通过预定义的 borderless 样式来实现。同样，也支持 XML 配置或者在界面控制器使用编程方法实现。
  1. <dateField id="dateField"
  2.            stylename="borderless"/>

当用编程方法实现的时候，选用 HaloTheme 类的以 DATEFIELD_ 开头的常量：

  1. dateField.setStyleName(HaloTheme.DATEFIELD_BORDERLESS);
dateField 的属性

align - caption - captionAsHtml - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datasource - dateFormat - description - descriptionAsHtml - editable - enable - box.expandRatio - height - icon - id - property - stylename - required - rangeEnd - rangeStart - requiredMessage - resolution - tabIndex - visible - width
dateField 的 XML 元素

validator
dateField 的预定义样式

borderless - small - tiny
API

addValueChangeListener - commit - discard - isModified - setContextHelpIconClickHandler