微调框

将 <input type='text'> 标记更改为旁边带有一对按钮的字段,这对按钮可用于将数字值或日期/时间值向上或向下“微调”指定的增量。

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

此组件可以对数字值或时间值进行微调,即,此组件与 NumberConverter 处理相同的数字值,并且能够处理 JSFDateConverter 指定的任何“时间”值。

JSFSpinner 组件对 <input> 字段添加了一对辅助控件按钮,这对按钮可用来增大/减小该字段中的值。

辅助控件按钮将添加到输入字段右边,并且上下堆叠。尽管现在添加了按钮,但输入字段却完整地保留了它的所有原始特征。例如,如果将输入字段宽度定义为 120px,则添加帮助控件按钮后,组合体组件的宽度现在也是 120px。这些按钮将采用与输入字段匹配的样式属性,例如,它们的边框与输入字段的边框重叠。应用于输入字段的适用属性(例如 disabled)也将影响这些按钮。

微调框可以应用于数字字段或者包含“时间”组件的日期时间字段,例如 hh:mm:ss。当应用于数字字段时,旋钮会将值增大/减小指定的增量,直到达到验证器(如果提供的话)中指定的最大值/最小值为止。如果将微调框应用于时间值,则旋钮会将值增大/减小指定的增量,直到达到验证器(如果提供的话)中指定的最大值/最小值为止。另外,可以对“时间微调框”指定其他增量,以便可以根据光标在该字段中的所处位置独立地增大/减小该值的每个组件(小时、分钟或秒)。例如,如果指定了多个增量,则当光标停留在字段的小时组件中时,值将按每小时为增量增大/减小;当光标停留在字段的分钟部分中时,值将按每分钟为增量增大/减小。

用户可以单击或按下旋钮。单击按钮时,会将值增大/减小一个增量。按下按钮将连续地增大/减小值,直到释放该按钮为止。

如果类型是“数字”,则 JSFSpinner 需要 NumberConverter;如果类型是“日期时间”,则需要 DateTimeConverter。此转换器用于在输入字段值(字符串)与 JavaScript™ 数字或日期时间对象之间进行转换。应该在构造微调框之前构造转换器,并且,应该将转换器 ID 传递给微调框。输入字段还可以有相关联的 NumberValidator 和/或 NumberAssist 组件或者 DateTimeValidaator 和/或 DateTimeAssist。如果某个验证器与输入字段相关联,则必须将其作为构造函数的属性传递给 JSFSpinner。验证器用来构造微调框的最小值和最大值界限,因此,强烈建议您提供验证器。如果某个“辅助”与输入字段相关联,则它不需要与 JSFSpinner 相关联。

发送组件的 JSF 标记

<hx:inputText>

基本 HTML

<input type="text">

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

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

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

JavaScript 构造函数

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

id

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

属性

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

属性

表 1. 微调框属性

属性名称

描述

类型

微调框(数字微调框或时间微调框)的类型。

converter

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

validator

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

increment

滑块中“记号”之间的增量。例如,如果最小值是 1,最大值是 10,则增量为 1 时将在 1、2、3、4、5、6、7、8、9 和 10 处绘制记号。在滑块中,只能选择标有记号的值。值可以是小数,例如 .01。

increment1

仅适用于时间,您可以根据光标在值中的位置,独立微调每个时间组件,即,小时、分钟和秒。如果指定了 increment1,则 increment 是光标在“小时”时间组件中时的增量,而 increment1 是光标在“分钟”时间组件中时的增量。如果未指定 increment2,则 increment1 是光标在“秒”时间组件中时的增量。值必须大于 .01。注意,如果提供了多个增量,则即使模式中没有分钟组件,也必须提供 increment2,这对 increment 同样成立。

increment2

仅适用于时间,您可以根据光标在值中的位置,独立微调每个时间组件,即,小时、分钟和秒。如果指定了 increment1,则 increment 是光标在小时组件中时的增量,increment1 是光标在分钟组件中时的增量,而 increment2 是光标在秒组件中时的增量。例如,如果指定 increment=3600、increment1=60 和 increment2=1 以及格式 hh:mm:ss,则意味着当光标在值的小时部分中时,微调将按 1 小时增加/减小值;当光标在值的分钟部分中时,微调将按 1 分钟增加/减小值;当光标在值的秒部分中时,微调将按 1 秒增加/减小值。值必须大于 .001。

button-border

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

button-color

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

CSS 类

应用于 input 标记的类确定了输入字段的样式,例如设置输入字段的边框,并通过进行扩展确定该字段旁旋钮的样式,该旋钮的样式与输入字段的边框匹配。没有用于独立进行旋钮样式化的专用 CSS。

API 调用

表 2. API 调用

API 调用

描述

redraw()

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

uirelease()

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

setValue(string)

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

object = getValue(boolean)

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

object = setAttribute(attribute)

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

string = getAttribute(attribute-name)

检索属性的当前值。

辅助功能

微调框可完全通过键盘进行访问。输入字段和两个旋钮都遵循跳进顺序。在输入字段中,向上方向键和向下方向键可以用来按增量增大/减小值。按向上方向键/向下方向键将按增量对值进行“微调”,直到释放该键为止。按钮获得焦点后,每次按下该按钮都会使值增大/减小。按下空格键将连续地增大/减小值,直到释放空格键为止。

目前,微调框不报告 XML 角色/状态,但它符合 XHTML 的标准。我们将尽快添加此报告功能。

局限性

示例代码

对数字格式为百分比的字段添加微调框。将微调框限制为包含 0% 至 100% 之间的值,并将增量设置为 1%。

hX.addConverter("x1", new hX.NumberConverter("strict:1", "pattern:##0%", "locale:,.%‰-$"));
hX.addValidator("x1", new hX.NumberValidator( "min-bound:0.0",  "max-bound:1.0",  "required:true"));
hX.addComponent("form1:text1", new hX.JSFSpinner("increment:.01","converter:x1","validator:x1"));

对格式指定了时间字段的字段添加微调框。指定三个不同的增量,以使微调框对光标在值中的所处位置敏感。

hX.addConverter("x16", new hX.DateTimeConverter("strict:1", "format:h:mm:ss a"));
hX.addComponent("form1:textTime3", new hX.JSFSpinner("type:datetime", "increment:3600",
                  "increment1:60", "converter:x16"));

反馈