日期拾取器

<input type="text"> 更改为旁边带有按钮的字段,该按钮可用来打开日期拾取日历。用户可以在输入区域中输入日期,也可以单击拾取器按钮并从日历中选择日期。

组合体组件的大小和形状与 <input> 标记相同,并且输入字段将保留对其所作的任何其他设置,例如输入辅助。

此组件与 DateTimeConverter 使用相同的日历。

JSFDatePicker 组件对输入字段添加了辅助控件按钮,该按钮可用来打开使您能够选择日期的日历。

辅助控件按钮将添加到输入字段右边。输入字段将保留其所有原始特征,并在原始特征的约束范围内添加辅助控件按钮。例如,如果将输入字段宽度定义为 120px,则添加帮助控件按钮后,组合体组件的宽度现在也是 120px。此按钮将采用与输入字段匹配的样式属性,例如,按钮边框与输入字段的边框重叠。应用于输入字段的适用属性(例如 disabled)也将影响此按钮。

日历所在弹出窗口的行为与 Windows® 弹出窗口相似。如果您单击该弹出窗口中的日期,该弹出窗口将关闭。如果单击页面中该弹出窗口外部的任何位置,该弹出窗口也将关闭。通常,该弹出窗口显示在输入字段下方并对齐左边。如果该弹出窗口在输入字段下方放不下,例如,该输入字段在窗口底部附近,则该弹出窗口将显示在输入字段上方。可以通过 CSS 类设置该弹出窗口的样式。

JSFDatePicker 需要 DateTimeConverter。此转换器用于在输入字段值(字符串)与 JavaScript™ 日期对象之间进行转换。此转换器也用于对日历中显示的月份、年份和星期进行格式化。应该在构造日期拾取器之前构造转换器,并且,应该将转换器 ID 传递给日期拾取器。该输入字段还可以与 DateTimeValidator 和/或 DateTimeAssist 组件相关联。如果某个验证器与输入字段相关联,则必须将其作为构造函数的属性传递给 JSFDatePicker。如果某个“辅助”与输入字段相关联,则它不需要与 JSFDatePicker 相关联。

发送组件的 JSF 标记

<hx:inputText>

基本 HTML

<input type="text">

日期拾取器的值将作为输入字段值进行传递。应该按照组件的相关转换器所描述的样式对该值进行格式化。如果最初未将任何值传递给页面,则拾取器将没有初始值。

支持所有与文本类型输入相关联的属性。

支持所有与文本类型输入相关联的事件处理程序。

JavaScript 构造函数

hX_5.addComponent("id", new hX_5.JSFDatePicker(attributes)); 其中

id

组件所连接至的 HTML 标记的 ID。

属性

逗号分隔的属性列表,其中每个属性都是一个加引号的字符串,此字符串包含使用冒号分隔的属性名称和值,例如,"label:MyLabel"。

属性

表 1. 日期拾取器属性

属性名称

描述

button-border

控制如何根据输入字段绘制弹出按钮。

button-color

指定按钮的背景色。缺省情况下,背景色与输入字段的边框颜色相匹配。

css-prefix

描述日历可视外观的 CSS 类集的基类。

converter

已构造的转换器的 ID。此转换器描述输入字段中值的格式。

first-day-of-week

被视为一周中的第一天的那天。零表示星期日。

multi-line

如果为 true,则日历上的标题将显示为两行,即年份和月份,分别包含控制月份和控制年份的单独按钮。如果为 false,则年份和月份将显示在一行上,该行带有仅控制月份的按钮。

validator

已构造的验证器的 ID。如果提供了验证器,则将使用此验证器中所描述的约束来限制用户可选取的值。

CSS 类

拾取器的 CSS 很复杂。应用于 input 标记的类确定了输入字段的样式,并通过进行扩展确定该字段旁弹出按钮的样式。另一组独立的类确定弹出窗口的样式。除非使用 css-prefix 属性覆盖各个弹出窗口的显示样式,否则,这组类将应用于页面中的所有弹出窗口。用于确定弹出窗口样式的那一组类遵循普通的 hxclient 命名约定,即,有一个基本类名,所有其他用于确定弹出窗口样式的类都使用带有后缀的基本名称。

缺省情况下,使用基类 inputText_DatePicker 来确定日历样式。可以使用 css-prefix 属性来指定另一个基类。

对输入字段指定的类确定了该输入字段及相关按钮的样式。除非对各个组件指定 css-prefix 属性,否则页面中所有日期拾取器弹出窗口的样式由 inputText_DatePicker 类以及相关子类确定。

表 2. 日期拾取器 CSS 类

CSS 类名

描述

base_DatePicker

对包含日历的 div 设置样式。注意,设置 div 的大小(宽度/高度)不会更改该 div 中日历的大小。要更改日历的大小,请使用 <base>-Size。

<base>-DatePicker-Size

对显示日历的表设置样式。该表嵌入在包含的弹出菜单 div 中。更改表的宽度和高度将更改日历的大小,包含的 div 将调整大小以适合此表。

<base>_DatePicker-Header

对日历表中包含三个标题行(年份行、月份行和工作日行)的表设置样式。

<base>_DatePicker-HeaderLine1

在标题表中,对表的第一行(年份行)中不包含年份的单元格设置样式。

<base>_DatePicker-HeaderLine2

在标题表中,对表的第二行(月份行)中不包含月份的单元格设置样式。

<base>_DatePicker-HeaderWeekday

在标题表中,对表的第三行(工作日行)中单元格设置样式。

<base>_DatePicker-HeaderYear

在标题表中,对第一行中包含年份的中间表单元格设置样式。

_DatePicker<base>-HeaderMonth

在标题表中,对第二行中包含月份的中间表单元格设置样式。

<base>_DatePicker-Button

在标题表的第一行和第二行中,对用于滚动日历的四个按钮设置样式。

<base>_DatePicker-Body

对日历表中包含各天的表设置样式。

<base>_DatePicker-CurrentMonth

在主体表中,对包含当前月份中某一天的表单元格设置样式。

<base>_DatePicker-OtherMonth

在主体表中,对包含的某一天不属于当前月份(例如,前一个月的后几天或者后一个月的前几天需要显示在当前所选月份的各天之前/之后)的表单元格设置样式。

<base_>DatePicker-InvalidDay

在主体表中,如果由于日期所连接的验证器不允许而未选中某一天,则对包含这一天的表单元格设置样式。

<base>_DatePicker-CurrentDay

在主体表中,对包含当前所选日的表单元格设置样式。

<base>_DatePicker-Today

在主体表中,对表示当前日期的表单元格设置样式。

<base>_DatePicker-CurrentToday

在主体表中,如果当前所选日与当前日期相同,则对表示今天的日期和当前所选日的表单元格设置样式。

<base>_DatePicker-Hover

定义样式以便在某一天获得鼠标或键盘焦点时,将此样式添加至这一天的样式。

注:
  • 旧版本的日期拾取器使用了 <base>-CurrentOtherDay 类。由于对拾取器进行了更改,因此已不再使用此类。
  • 用于确定弹出窗口样式的基类支持三类效果,在某些浏览器中,这些效果将应用于弹出窗口 div。并非所有浏览器都支持这些效果。如果浏览器不支持某个效果,就不会显示该效果。
    要使菜单背景透明,即仅使背景透明,而不是使前景中的文本透明,请使用:
    -moz-opacity: .9;
    opacity: .9;

    要在 Mozilla 和 Internet Explorer(IE)中呈示此样式,必须同时提供这两个属性。opacity 值必须是 0 到 1。

    要使菜单显示阴影,请使用:
    outline-color: #E4E4E5;
    outline-width: 1px;
    -moz-outline-color: #E4E4E5;
    -moz-outline-width: 1px;

    要使 Mozilla 和 IE 浏览器能够显示此菜单,必须同时提供这两组属性。color 指定阴影中颜色最深部分的颜色。width 指定阴影的宽度,最小值为 1。阴影将绘制在菜单右边和底部。

    只有在 IE 中才能将过渡效果应用于菜单,例如,它可以滑动到位。过渡效果是通过 IE 滤镜效果指定的。例如:
    filter:progid:DXImageTransform.Microsoft.Inset(duration=.4);

    例如,如果检测到滤镜,则它将挂起(不播放)直到菜单显示为止。应用滤镜后,菜单的样式才更改为可视并向后“播放”。

    注意,Microsoft® 现在建议您不要在对任何类型的文本应用了过渡效果时使用他们的过渡滤镜。这是因为,他们的 ClearType 代码包含一个错误,该错误导致文本在过渡效果运行期间显示为黑色粗体。(其原因在于,ClearType 子像素呈示算法包含一个固有的缺陷并且无法修正。ClearType 只有在使用 LCD/Plasma 显示器的计算机上才可用,因此,您可能从未见过此功能打开。)

API 调用

表 3. 日期拾取器 API 调用

API 调用

描述

redraw()

重新绘制组件时将对基本标记的特性/属性所作的任何更改考虑在内。

uirelease()

释放与组件相关联的任何活动 UI。

setValue(string)

设置组件的值并确保提供的值有效。

object = getValue(boolean)

检索组件的值。如果该 boolean 为 false,则此函数等价于获取基本标记的值。如果该 boolean 为 true,则此值将作为 JavaScript 日期/时间对象返回,而不是作为字符串返回。

object = setAttribute(attribute)

设置属性,或如果以前已设置属性,则更改其值。

string = getAttribute(attribute-name)

检索属性的当前值。

辅助功能

日期拾取器可完全通过键盘进行访问。输入字段和日期拾取器按钮都遵循跳进顺序。在输入字段中,向上方向键和向下方向键可以用来将日期增大/减小一天。按向上方向键/向下方向键时,将以一天为增量对日期进行微调,直到释放该键为止。当该按钮带有焦点时,按空格键或回车键将显示日历,并且焦点将移至该日历中的当前选择。当日历带有焦点时,按空格键或回车键将选中当前所选日期,从而关闭日历并将焦点返回到该按钮。按 ESC 键将关闭该日历,从而将焦点返回到该按钮并保持值不变。按向左、向右、向上和向下方向键将更改所选日期。按 SHIFT + 向左/向右方向键将更改月份,按 SHIFT + 向上/向下方向键将更改所选年份。

目前,日期拾取器不报告 XML 角色/状态,但它符合 XHTML 的标准。我们将尽快添加此报告功能。

局限性

示例代码

对日期格式为 MMM d,yyyy 的字段添加日期拾取器。将有效日期限制为从二月开始的双数月。

<input type="text" id="form1:text01" class="inputText" size="20" value="Feb 3, 2006" />
<script>
hX.addConverter("c", new hX.DateTimeConverter("strict:1", "format:MMM d, yyyy"));
hX.addValidator("20", new hX.DateTimeValidator("constraint-expression:@testValue.month==1 ||
                  @testValue.month==3 || @testValue.month==5 || @testValue.month==7 ||
                  @testValue.mongth==9 || @testValue.month==11"));
hX.addComponent("form1:text01", new hX.JSFDatePicker("converter:c","validator:20",
                  "first-day-of-week:0"));
</script>

反馈