颜色拾取器

<input type="text"> 标记更改为旁边带有按钮的字段,该按钮可以打开用于拾取颜色的调色板。此组件仅支持选择,这意味着用户无法输入颜色名,而是必须从颜色列表中选择颜色。

JSFColorPicker 组件对 <input> 字段添加了辅助控件按钮,该按钮可以弹出用于选择颜色的调色板。输入字段的内容将显示为颜色样品,并可以选择在颜色样品中显示所选颜色的名称。

JSFColorPicker 是只允许进行选择的组件,您无法输入颜色。即,此组件包含预定义的可允许选项列表。系统已指定所允许的颜色列表作为此组件的属性。指定的颜色是十六进制值,并且带有与该十六进制值匹配的可选名称。这类似于包含多个 <option> 子标记的 HTML <select> 标记,每个 option 子标记指定一个值以及该值的标签。

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

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

发送组件的 JSF 标记

<hx:selectOneColor>

基本 HTML

<input type="text">

颜色拾取器的值将作为输入字段值进行传递。此值应该是组件构造函数中指定的其中一个十六进制颜色值。如果最初未将任何值传递给页面,则拾取器将没有初始值。

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

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

JavaScript 构造函数

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

id

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

属性

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

表 1. JSF 颜色拾取器属性

属性名称

描述

button-border

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

button-color

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

css-prefix

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

颜色

分号分隔的十六进制颜色值列表,这些值表示用户可从调色板中选取的颜色。

color-names

列表中每种颜色的用户友好名称的相应列表。

show-labels

如果指定,则当前所选颜色的名称将显示在输入字段中该颜色样品的上面。如果省略,则名称不显示,并且输入字段将仅显示一种颜色样品,指示当前所选颜色。注意,为了方便访问,在任何情况下,颜色名称都在输入字段中,此选项使名称可视。

缺省调色板包含下列颜色:
"#FDDDCE";"#FFD990";"#FFF799";"#C4DF9B";"#B3FFB2";"#7FCBAE";"#81D3EB";"#ADCDEC";"#D3B6D7";"#FCDEE0";
"#CC6666";"#FF9900";"#D3BD2A";"#8FB73E";"#6DB286";"#4F9BAA";"#6D9AB4";"#6F85C2";"#897AB9";"#B7798E";
"#ED1C24";"#FF6600";"#FFFF00";"#9ACA3C";"#00FF00";"#00FFFF";"#0000FF";"#4F57A6";"#800080";"#FF00FF";
"#FFFFFF";"#F2F2F2";"#E5E5E5";"#D9D9D9";"#CCCCCC";"#B3B3B3";"#999999";"#808080";"#666666";"#000000";

CSS 类

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

缺省情况下,使用基类 inputColor_ColorPicker 来确定弹出窗口样式。可以使用 css-prefix 属性来指定另一个基类。

再次声明,对输入字段指定的类确定了该输入字段及相关按钮的样式。除非对各个组件指定 css-prefix 属性,否则页面中所有颜色弹出窗口的样式由 inputColor_ColorPicker 类以及相关子类确定。

表 2. JSF 颜色拾取器 CSS 类

属性名称

描述

base_ColorPicker

对包含弹出窗口的最外侧 div 设置样式。通常,不应该在这个类中以显式方式设置高度和宽度属性,相反,指定网格单元格的大小,弹出菜单的大小将根据网格单元格的大小进行调整。

<base>_ColorPicker-Body

对将弹出菜单组织到网格的最外侧表设置样式。

<base>_ColorPicker-GridCell

对表中的单个网格(表)单元格设置样式。

<base>_ColorPicker-GridSwatch

对网格单元格中颜色的单个样品设置样式。

<base>_ColorPicker-GridCell-Selected

指定表示当前所选颜色的(一个)网格单元格的样式。

<base>_ColorPicker-GridCell-Hover

指定具有键盘或鼠标焦点的网格单元格的样式。

<base>_ColorPicker-GridCell-Hover-Selected

指定同时具有键盘或鼠标焦点和所选项的网格单元格的样式。

注: 用于确定弹出窗口样式的基类支持三类效果,在某些浏览器中,这些效果将应用于弹出窗口 div。并非所有浏览器都支持这些效果。如果浏览器不支持某个效果,就不会显示该效果。

API 调用

表 3. JSF 颜色拾取器 API 调用

API 调用

描述

redraw()

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

uirelease()

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

setValue(string)

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

object = getValue(boolean)

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

object = setAttribute(attribute)

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

string = getAttribute(attribute-name)

检索属性的当前值。

辅助功能

颜色拾取器可完全通过键盘进行访问。对于组合框而言,将输入区域和拾取器按钮视为跳进顺序中的单一实体。当组件带有焦点时,按向上方向键和向下方向键将打开弹出窗口并将焦点移至该弹出窗口。当弹出窗口带有焦点时,按空格键或回车键将选中当前所选颜色,从而关闭弹出窗口并将焦点返回到该组件。按 ESC 键将关闭该弹出窗口,从而将焦点返回到该组件并保持值不变。按向左、向右、向上和向下方向键将更改带焦点的颜色样品。按 Home、PgUp、End 和 PgDn 键会将焦点移至调色板中的第一个/最后一个颜色。

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

示例代码

对页面添加包含 32 种颜色的颜色拾取器。最初,选择了白色。

<input type="text" id="form1:text01" class="inputColor" size="20" value="#FFFFFF" />
<script>
hX.addComponent("form1:text01", new hX.JSFColorPicker(
    "colors:#FDDDCE;#FFD990;#FFF799;#C4DF9B;#B3FFB2;#7FCBAE;#81D3EB;#ADCDEC;#D3B6D7;#FCDEE0;#CC6666;#FF9900;#D3BD2A;#8FB73E;#6DB286;#4F9BAA;#6D9AB4;#6F85C2;#897AB9;#B7798E;#ED1C24;#FF6600;#FFFF00;#9ACA3C;#00FF00;#00FFFF;#0000FF;#4F57A6;#800080;#FF00FF;#FFFFFF;#F2F2F2;#E5E5E5;#D9D9D9;#CCCCCC;#B3B3B3;#999999;#808080;#666666;#000000",
    "color-names:pale red;pale orange;pale yellow;pale avocado;pale green;pale cyan;pale blue;pale cerulean;pale purple;pale magenta;dull red;dull orange;dull yellow;dull avocado;dull green;dull cyan;dull blue;dull cerulean;dull purple;dull magenta;red;orange;yellow;avocado;green;cyan;blue;cerulean;purple;magenta;white;very pale gray;pale gray;very light gray;light gray;gray;medium gray;dark gray;very dark gray;black"));
</script>

反馈