组件对象

一个 JavaServer Face(JSF)组件,它通过扩展 HTML DOM 对象为其提供其他输入和输出功能以及对其进行可视化。

使用 JSF 组件对象

组件将尽可能多地保留原始标记功能。它们将提供新的标记类型。例如,可以将日期拾取器想象成 <input type="datepicker"> 标记,其中,生成的对象将保持 input 标记的大小、CSS 属性、在一行内显示、跳进顺序、Z 顺序、语言特征和事件。

通常,组件扩展 input 标记和/或 div。某些组件用来构建其他组件,例如菜单项。

大部分组件对页面添加可视元素。例如,日历组件在页面上绘制日历。组件的可视元素由一组 CSS 类控制,这些 CSS 类定义了该组件的整体外观以及该组件中特定元素的外观。

要使用 JSF 组件对象,请执行下列操作:
  1. 通过对页面添加 CSS,设置对象的样式。例如:
    <style>
    .button1, .button1_moused {
        width:100px;
        height:21px;
    }
    .button1_Label, .button1_Label_moused {
        font-family:sans-serif;
        color:black;
        font-size:14px;
        text-align:left;
        margin-left: 24px;
    }
    </style>
  2. 在页面中添加要应用该行为的标记。例如:
    <input type="submit" class="MenuBar_button2b" id="form1:button2" alt="New" title="New" value="New" />
  3. 将该组件连接到 DOM 对象。例如:
    <script>
        hX.addComponent("form1:button2", new hX.JSFImage("normal:img/search-button.gif",
        "moused:img/search-button-moused.gif", "label:New"));
    </script>
在此示例中,图像组件对 input 标记进行了修改。此组件显示带有文本的图像,并且,当用户执行鼠标操作时,此组件的显示将更改。

用于创建/查找组件的 hx 调用

每个组件都是使用 JavaScript 构造函数进行构造,并通过 addComponent 调用添加到页面中。

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

id

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

name

JSF 组件的名称。

属性

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

注: 对于一个 DOM 对象,只有一个组件可以与其连接。

诸如菜单栏之类的组件包含子组件。要构造子组件:

hX_5.addSubComponent ("parent-id", "id", new hX_5.JSFName(attributes), position);

parent-id

作为此子组件父代的 JSF 组件的 ID。

id

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

name

JSF 组件的名称。

属性

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

position

此子组件相对于其他具有相同父代的子组件的位置。如果省略,则将追加该子组件。

还可以使用以下语法成批添加子组件:

hX_5.addSubComponent ("parent-id", [ new hX_5.JSFName(attributes), ... ]); 其中

parent-id

作为此子组件父代的 JSF 组件的 ID。

name

JSF 组件的名称。

属性

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

要除去子组件:

var x = hX_5.removeSubComponent("parent-id", "id"); 其中

parent-id

作为此子组件父代的 JSF 组件的 ID。

id

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

要获得特定的组件对象:

var o = hX_5.getComponentById("id"); 其中

id

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

returns

类型为转换器(数字、日期时间或字符串)的 JavaScript™ 对象。如果不能完成转换,则将返回 NULL 并设置 lastError。

要获取 DOM 对象中的所有组件,例如所有与 div 中所有标记相连接的组件:

var a = hX_5.getComponentsInId("id"); 其中

id

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

returns

类型为转换器(数字、日期时间或字符串)的 JavaScript 对象。如果不能完成转换,则将返回 NULL 并设置 lastError。

要获取子组件对象:

var o = hX_5.getSubComponentById("id"); 其中

id

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

returns

类型为转换器(数字、日期时间或字符串)的 JavaScript 对象。如果不能完成转换,则将返回 NULL 并设置 lastError。

要获取子组件的父代:

var x = hX_5.getParentComponentById("id"); 其中

id

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

returns

类型为转换器(数字、日期时间或字符串)的 JavaScript 对象。如果不能完成转换,则将返回 NULL 并设置 lastError。

组件的常用 API 调用

更改组件或子组件的属性:

c.setAttribute("arg"); 其中

c

组件对象。

arg

JSF 属性/值字符串。

获取组件或子组件的属性:

var x = c.getAttribute("argname"); 其中

c

组件对象。

argname

包含属性的名称的字符串。

returns

类型为转换器(数字、日期时间或字符串)的 JavaScript 对象。如果不能完成转换,则将返回 NULL 并设置 lastError。

根据对基本标记的特性或属性所作的任何更改重新绘制组件。当特性或属性更改时,执行此操作:

var x = c.redraw(); 其中

c

组件对象。

释放组件中的任何活动 UI 元素,例如取消选择该组件中的任何按钮:

var x = c.uirelease(); 其中

c

组件对象。

设置组件的值。对于基于 input 标记的组件,这相当于设置 input 标记的 value 属性。并且,还将确保提供的值有效,即,将对其进行转换和验证。

var x = c.setValue("string"); 其中

c

组件对象。

string

要转换的字符串

获取组件的值。对于基于 input 标记的组件,这相当于获取 input 标记的 value 属性。并且,还将确保提供的值有效,即,将对其进行转换和验证。

var x = c.getValue(boolean); 其中

c

组件对象。

boolean

将返回值强制转换为相应类型的 JS 对象。

returns

类型为转换器(数字、日期时间或字符串)的 JavaScript 对象。如果不能完成转换,则将返回 NULL 并设置 lastError。

响应底层对象的更改

组件将修改基本 HTML DOM 对象,例如,日期拾取器将修改 input 标记。如果通过编程更改基本标记,例如将该标记禁用,则该组件应该会采用该更改并作出反映。

例如,如果将基本标记禁用,则该组件也将被禁用。浏览器局限性和组件实现局限性可能会导致无法采用并反映更改。更改基本标记时,如果组件未采用该更改,则您需要通知该组件已进行了更改。这可以通过调用组件的 redraw 函数实现:
// Get an html tag and disable it
var obj = document.getElementById("form1:text1");
obj.disabled = true;
// Force the component to acknowledge the change
var c = hX_5.getComponentById("form1:text1");
c.redraw();

注意,通过设置样式属性对基本对象样式所作的直接更改或者通过更改 CSS 规则进行的间接更改都不会被采用,在这些情况下,必须调用 redraw 函数。

在某些情况下,无法修改基本对象的特定特性或属性。这些限制非常罕见,在组件的文档中已有阐述。通常,这些限制特定于值,例如,无法将组件大小由按比例更改为绝对大小。

表 1. 组件对象

组件

描述

JSFCalendar 将输入字段修改为用于选择日期的小型日历。
JSFColorPicker 将输入字段修改为用于选择颜色的组合框。
JSFDataTable 管理高级 JSF 数据表功能的客户端交互,例如垂直滚动和选择,等等。
JSFDatePicker 将输入字段修改为包括一个按钮,该按钮将弹出用于选择日期的小型日历。
JSFDialog 对 div 进行修改,将其放入模态或非模态对话框。
JSFImage 对按钮或图像进行修改,使其包含多个图像或文本以及/或者具有多种状态,例如正常、鼠标悬停、按下和禁用。
JSFMenu 将 div 修改为菜单或树型菜单(菜单栏)。
JSFMenuItem(子组件) 菜单中的元素。
JSFProgressBar 将 div 修改为进度条。
JSFSection 将 div 修改为可折叠或可展开的部分。
JSFSlider 将输入字段修改为包括一个按钮,该按钮将弹出用于选择字段值的滑块。
JSFSpinner 将输入字段修改为包括一对微调框按钮,这对按钮可以按指定的间隔增大或减小字段值。
JSFTwistie 对任何 HTML 事件处理程序提供绑定功能或操作。
相关概念
JSF 窗口小部件库(JWL)

反馈