HOME / Docs & Support / NetBeans 5.5

>> 更多 Visual Web Pack 文档

深入研究组件

撰稿人：Visual Web Pack 教程编写小组

2007 年 5 月 [修订号：V5.5.1-1]

组件是一些用来构建交互式 Web 页的模块。本教程介绍了有效利用 Visual Web Pack 捆绑的组件时所需了解的一些基本知识。在熟悉了基本知识以后，您可以进一步学习各个组件教程以了解更多的特定信息。您还可以在组件面板中的任何组件上按 F1 键，以获取该组件的详细信息。

本教程详细介绍了 NetBeans Visual Web Pack 5.5 入门指南和开发 Web 应用程序中引入的概念。

-	组件的概念
-	常规信息
-	输出组件
-	输入组件
-	操作和链接组件
-	布局组件
-	非可视组件
-	小结

本教程将使用以下技术和资源

JavaServer Faces 组件/ Java EE 平台	1.2/Java EE 5* 1.1/J2EE 1.4
Travel 数据库	不是必需的
BluePrints AJAX 组件库	不是必需的

* 该教程发布时，只有 Sun Java System Application Server 支持 Java EE 5。

本教程是针对使用 Sun Java Application Server PE 9.0 Update Release 1 和 Tomcat 5.5.17 进行定制的。如果您使用的是其他服务器，请参考发行说明和常见问题解答以了解已知问题和解决方法。有关支持的服务器和 Java EE 平台的详细信息，请参见发行说明。

组件的概念

生成一个静态 HTML 页并不需要花很多的时间，同时也不需要深入地了解更多的知识。然而，如果要生成动态的交互式页面，则需要接触一个复杂的领域。您必须了解如何将 JavaScript 用于客户端交互，同时还必须编写 Java 代码和 JavaServer Pages (JSP) 标记以用于服务器端的交互和验证。另外，由于不同的浏览器在显示标记时存在许多差异，因此您的效率可能会降低至零。

利用 Visual Web Pack 提供的基于 JavaServer Faces 的组件可以简化交互式 Web 页的构建过程，并且可以加快开发周期。此外，您无需了解错综复杂的 JavaServer Faces 技术，便可以使用 Visual Web Pack 提供的这些组件。

组件是增强型标记。也就是说，组件不仅可以呈现为标记（如下拉列表），而且组件标记易于修饰，便于得到炫丽的外观；使用简单的 Java 代码还可以处理组件生成的事件。例如，文本字段组件使用 JavaServer Faces 框架来转换和验证输入内容，同时应用更改并验证事件。

此外，您只需执行几次单击操作，就可以将组件的属性与 Bean 属性绑定或者与数据源的数据提供器包装器绑定，无论数据源是数据库、Web 服务、数组还是列表。通过使用绑定功能，您无需编写代码来填充组件值，也无需编写代码将组件值保存到绑定对象中。

捆绑的组件具有超凡的功能，这是您使用普通的 HTML 标记所无法企及的。例如，下图所示的表组件具有对列进行排序和自动分页的功能。

图 1：表组件

Visual Web Pack 提供了两组捆绑的组件。一组基于 JavaServer Faces 1.1 技术，另一组基于 JavaServer Faces 1.2 技术。组件面板提供的组件与为 Web 应用程序项目设置的 Java EE 版本相兼容。如果将 Java EE 版本设置为 Java EE 5，则组件面板将提供与 JavaServer Faces 1.2 兼容的组件。如果将 Java EE 版本设置为 J2EE 1.3 或 1.4，则组件面板将提供与 JavaServer Faces 1.1 兼容的组件。

本教程主要介绍在组件面板的“基本”、“布局”和“组合”类别中包含的组件，如下图所示。

图 2：“基本”、“布局”和“组合”类别

注意：组件面板中的“标准”类别包含了 JavaServer Faces 引用实现组件。由于标准组件提供的功能较少且需要较多编程工作，因此应该使用组件面板其他类别中的可视组件。

注意：组件面板提供了表单组件，本教程将不讨论表单组件。在大多数情况下，虚拟表单机制是一种很好地处理页面上多个表单的方式。

常规信息

此部分提供了适用于大多数组件或所有组件的信息。本教程的其余内容分为五部分（输出组件、输入组件、操作和链接组件、布局组件和非可视组件），如下图所示。

图 3：五种类型的组件

组件属性

使用“属性”窗口可以指定组件的外观和行为。例如，使用列表框组件的 rows 属性可以指定呈现的列表框的长度，使用 multiple 属性可以指定页面访问者是否可以选择列表中的多项。

Visual Web Pack 还为每个组件的常见任务提供了菜单操作。例如，图像组件具有“设置图像”菜单项，静态文本组件具有“编辑文本”菜单项，下拉列表组件具有“编辑标签”菜单项。

下表描述了控制组件的行为和外观的公共属性。接下来的各部分将介绍不同类型组件的特定信息。

属性描述

id 每个组件都必须具有一个 id，且 id 对其所在的页面来说是唯一的。IDE 在您将组件添加到页面时创建 id。对于以下情况，您可能希望更改组件的 id：

组件是输入组件。为组件指定对应于它所绑定的属性或列的 id，如 personIdDropDown。

组件（如按钮）生成操作事件。将 id 设置为与组件的标签匹配的动词名称，如 submitButton。

如果页面上具有一些相同类型的组件，并且需要编写 Java 源代码以设置或访问其中一些组件的属性值。例如，如果引用 nameTF 和 addressTF 而不是 textField1 和 textField2，则代码会更易于理解。

toolTip 使用此属性可以指定页面访问者将鼠标悬停在组件上时出现的文本。

style 使用 style 属性可以更改以下设置：

字体

背景

文本块

边框

边距

位置

单击 style 属性的省略号 (...) 按钮将打开样式编辑器，该编辑器允许您轻松地更改设置并预览结果。有关如何使用此编辑器的描述，请单击位于编辑器底部的“帮助”按钮。

通常，当您调整组件的大小时，IDE 会设置高度、宽度或同时设置两者。如果页面处于网格布局模式，则在您将组件拖放到页面上以及在页面上重新定位该组件时，IDE 会设置位置值。

有时，您会看到与样式设置类似的实际属性，如 bgcolor 或 border。这些是标准的 HTML 4 样式属性。style 属性是对这些标准属性的增强，它提供了更好地配置组件外观的机制。
组件集用于实现 Web UI 的缺省主题，该主题是一组相互作用的层叠样式表 (Cascading Style Sheet, CSS) 文件。通过建立样式设置，您可以覆盖主题的大多数（但不是所有）样式功能。例如，您不能使用 style 属性来设置表的背景色或设置 label 属性的字体颜色。这尤其适用于设置与组件的主题发生冲突的情况。此外，在某些情况下，特定区域还会被可能具有不同样式设置的其他子组件所遮盖。

styleClass 每个项目都具有一个主题，主题是层叠样式表 (Cascading Style Sheet, CSS)、JavaScript 文件和图标图像的集合。Visual Web Pack 提供了 Web UI 的缺省主题。要将自己的样式添加到主题中，请使用样式表编辑器或将样式表放置在项目的 resources 文件夹中。styleClass 属性的下拉列表显示了应用程序使用的所有样式表的所有样式类。通常，除非要从自己的样式表中选择样式类，否则不使用此属性。除了组件的主题样式类之外，还将应用 styleClass 设置。

visible visible 属性指定呈现的组件在页面上是否可见。当将组件的 visible 属性设置为 false 时，该组件不出现在呈现的页面上，但是它仍出现在发出的 HTML（页面源代码）中，它的值将被提交，而且该组件的所有转换、验证和事件生成仍会发生。

rendered 如果将组件的 rendered 属性设置为 false，则从发出的 HTML 中删除该组件，这样该组件对于客户端就是不可用的。此外，您无法通过 JavaScript 引用该组件，而且在提交页时也不会发生转换、验证或生成事件。

设置组件值

所有输入组件和输出组件都是包含值的组件。例如，文本字段组件包含文本，列表框组件包含选定的值。设置输入组件和输出组件的值有以下几种方法：

设置组件的包含值的属性。在“属性”窗口中，单击包含值的属性的省略号按钮 (...) 可以打开文本编辑器。此外，对于大多数输入组件和输出组件，您可以在可视设计器中选择组件，然后键入组件的值。对于组件的可编辑文本，包含值的属性的弹出式菜单包含“编辑”菜单项。
通过页面 Bean 的源代码调用组件的 setter 方法。例如，调用 setText 方法可以设置文本字段组件的值，调用 setSelected 方法可以设置列表框组件的值。在 preprocess、prerender、value change 和 action 方法中，会经常调用 setter 方法。
将组件绑定到数据提供器或 Bean 属性。有关将组件绑定到数据的详细信息，请参见下一子部分。

注意：与 JavaServer Pages 实现一样，当服务器通过 JSP 源代码构造页时，JSP 源代码中的标记属性设置要优先于运行时设置。例如，如果将静态文本组件的 text 属性设置为 "moon"，则 IDE 会将 text="moon" 添加到 JSP 文件中静态文本组件的标记中。即使此页的 prerender 方法包含 staticText1.setText("sun") 语句，在应用程序呈现此页时，静态文本组件也会显示 "moon"。如果重新呈现此页，则 staticText1.setText("sun") 语句将生效，并且静态文本组件将显示 "sun"。如果先访问其他页然后再返回来访问此页，则服务器将再一次通过 JSP 源代码构造此页，将优先使用在 JSP 标记属性中设置的值，即此页将显示 "moon"。

提示：为确保属性设置代码始终生效，请不要在“属性”窗口中将该属性设置为静态值。

绑定到数据

您可以将大多数的输入组件和输出组件绑定到数据对象。通过将组件绑定到数据，Web 应用程序可以自动将组件的值与绑定目标的值进行同步。例如，如果将组件绑定到 Bean 属性，则 Web 应用程序在其呈现页时会将组件的值设置为 Bean 属性的值，而在提交页时会更改 Bean 属性的值以便与对组件值进行的更改匹配。

Visual Web Pack 包含数据库表、Web 服务、Enterprise JavaBeans 对象、映射、数组和列表的数据提供器包装器。您可将数据提供器与数据对象关联，并将组件绑定到数据提供器。使用数据提供器的一个优点是：它们提供了访问所有类型数据的公共接口。

要为数据库表创建数据提供器，请将数据库表从“运行环境”窗口的“数据库”部分拖放到页面上，或者拖放到页面中的组件上。IDE 将为数据库表创建 CachedRowSet 表数据提供器。

有关绑定和数据提供器的详细信息，请参见使用数据绑定组件访问数据库教程。

转换值

Visual Web Pack 提供了一些可应用于大多数输入组件和输出组件的转换器。转换器将对象的值转换为 String 值，以便可以将该值写入 HTML 响应。相反，转换器将 HTML 请求中的 String 值转换回指定的数据类型，如 Boolean 或 Float。

注意：对于绑定到数据的任何组件，Web 应用程序会自动执行相应的转换。例如，如果将文本字段组件绑定到 Integer 对象，则 Web 应用程序会自动将输入值 (String) 转换为 Integer 值。

输出组件

Visual Web Pack 提供了一些输出组件，如下图所示。这些组件分为以下三组：文本、消息和图像。通常，使用输出文本组件可以在页面上设置文本布局，使用输出消息组件可以响应用户输入或用于其他类型的动态操作，使用图像组件可以显示像素值库，如 jpg 或 gif 文件。

图 4：输出组件

输出文本组件

Visual Web Pack 提供了三种输出文本组件。

输出文本组件	用法
静态文本	当希望仅在页面上显示某些文本时，可以使用静态文本组件。
标签	使用标签组件可以将文本与输入组件关联。通过设置标签组件的 `for` 属性，可以将该标签组件与输入组件关联。将标签组件与输入组件关联时，该标签组件将变得“更智能”。具体说来，如果输入组件的 `required` 属性为 `true`，则标签组件将显示一个星号。如果因输入无效而导致服务器拒绝了该页面的提交申请，则会在页面中突出显示标签组件的文本。尽管输入组件确实具有 `label` 属性，但是最好使用标签组件，因为在设置输入组件的 `label` 属性时，无法调整该组件的大小或正确地将其对齐。此外，使用标签组件时还可以拥有更多的样式选项。
内联帮助	使用内联帮助组件可以在页面上显示简短的帮助类型信息。

输出消息组件

Visual Web Pack 提供了以下输出组件以显示各种类型的消息。这些组件（除页面警报组件之外）仅在其值不为空时出现在呈现的页面上。

输出消息组件	用法
警报	使用警报组件可以在某个事件完成时显示动态信息，如警告、错误、成功状态或信息性状态。您可以选择将错误图标、信息图标、警告图标或成功图标与摘要文本一起显示，还可以选择显示详细文本和超级链接。使用 `summary` 和 `detail` 属性可以设置组件的文本，使用 `type` 属性可以指定要显示的图标。仅当组件的 `summary` 属性具有值时，该组件才出现在页面上。通过指定 `linkText` 和 `linkURL` 值，可以添加可选的超级链接。除非 `detail` 属性具有值，否则不会在组件中显示 `linkText` 值。要指定链接的动态页面导航，请执行以下步骤：设置 `linkText` 属性。使用页面导航编辑器在页面的连接器端口和目标页面之间创建连线。为连线指定名称，如 `alertOutcome`。切换至可视设计器，然后双击警报组件。IDE 将创建操作事件处理程序方法，并在 Java 编辑器中将插入点置于该方法上。更改方法的 return 语句以使其返回为连线指定的名称，如 `alertOutcome`。请注意，此过程与其他操作组件的步骤（如操作和链接组件中所述）稍有不同。这是因为页面导航仅允许来自页面和来自扩展 `UICommand` 的组件的连线，而警报组件不扩展 `UICommand`。
页面警报	页面警报组件与警报组件类似，只是它用于在单独的页面上显示动态消息。页面警报组件允许您从错误、警告、信息和问题图标中选择要显示的图标。您可以使用 `title`、`summary` 和 `detail` 属性来设置组件的文本，并且使用 `type` 属性来指定要显示的图标。
消息	使用消息组件可以显示输入组件的错误消息。要将消息组件与输入组件关联，请设置消息组件的 `for` 属性。应用程序将有关转换和验证错误的消息发送到消息组件。在抛出以下任意一种异常的情况下，应用程序会将您自己的验证消息发送到消息组件： `ValidatorException(new FacesMessage(summary))`. `ValidatorException(new FacesMessage(summary, detail)).` `ValidatorException(new FacesMessage(severity, summary, detail))`. 对于 severity 参数，您可以传递 `FacesMessage.SEVERITY_INFO`、`FacesMessage.SEVERITY_WARN`、`FacesMessage.SEVERITY_ERROR` 或 `FacesMessage.SEVERITY_FATAL`。对于 JavaServer Faces 1.2 组件集，您可以调用组件的 `requiredMessage`、`converterMessage` 和 `validatorMessage` 方法来指定定制消息，从而覆盖标准的错误消息。
消息组	使用消息组组件可以显示运行时错误。您也可以显示单个组件的错误（如验证和转换错误），方法是取消选中 `showGlobalOnly` 属性的复选框。消息组组件对于诊断编程错误来说，是非常有用的。要将您自己的文本写入此组件，请调用 `info(String summary)`、`warn(String summary)`、`error(String summary)` 或 `fatal(String summary)`。Web 应用程序会根据方法的严重性级别将不同的样式应用于文本。要同时写入摘要消息和详细信息消息，请使用 `FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(summary, detail))` or `ValidatorException(new FacesMessage(severity, summary, detail))`。您必须选中组件的 `showDetail` 复选框，才能显示详细信息消息。

就像输出文本组件那样，您可以通过编程方式设置页面警报和警报组件的输出值，方法是调用相应属性的 setter 方法。例如，要设置页面警报组件的摘要文本，请调用 setSummary(String)。您还可以将这些属性绑定到受管 Bean 属性和数据提供器字段。

图像组件

使用图像组件可以显示由 url 属性指定的图形图像，或显示提供的某个图标，如 ALARM_CRITICAL_MEDIUM 或 ALERT_OK_SMALL（您可以通过 icon 属性的下拉列表进行选择）。

图 5：图像组件示例 图 5：图像组件示例

url 属性可以包含 Internet 上图像的 URL，或者也可以指向项目 resources 文件夹中的图像文件，如 /resources/images/duke.gif。您还可以将 url 属性绑定到受管 Bean 属性或绑定到返回 String 格式的 URL 路径的数据提供器字段。通过单击 url 属性的省略号 (...) 按钮，您可以选择“使用绑定”单选按钮将属性绑定到数据对象，或者也可以选择“使用值”单选按钮指定图像文件。如果图像尚未包含在 resources 文件夹中，请单击“添加文件”以查找该文件，然后将其复制到此文件夹中。或者，您也可以在 url 属性的文本框中键入有效的 URL。

提示：在您指定与 Web 应用程序打包在一起的图像的 URL 时，请使用相对于上下文的 URL。即，URL 以正斜杠 (/) 开始，如 /resources/images/dot.gif。使用相对于上下文的 URL 时，在呈现页并将其发送到客户端之前，服务器会将 URL 转换为完整的 URL。如果开始处没有正斜杠，则会在客户端上进行解释，而且客户端会将当前页位置的 URL 附加到图像 URL 的前面。如果页面位于子文件夹中，则在转发请求（缺省的分发机制）时可能无法正确解析 URL。

输入组件

如下图所示，Visual Web Pack 提供了一些获取用户输入的不同方法。此部分描述了输入组件，讨论了这些组件的通用功能，并说明了如何获取和处理输入值。

图 6：输入组件

Visual Web Pack 提供了以下输入组件。

输入组件用法

文本输入组件使用文本字段组件可以输入单行文本，使用文本区域组件可以输入多行文本。口令字段组件可以用作输入字段，该字段将输入字符回显为屏蔽输入内容的替代字符。

选择组件

单选按钮组组件、复选框组组件、下拉列表组件、列表框组件以及添加删除列表组件都非常类似。它们都提供了项（显示值）的列表，页面访问者可以从中选择一个或多个选项。

选择组件中的每个项都具有一个基础返回值（如果页面访问者选择了该选项，则 selected 属性的值将返回此基础值）。

初始化项列表有以下几种方法：

使用缺省选项组件。当您将选择组件添加到页面时，IDE 会创建缺省选项组件，并将其绑定到选择组件。缺省选项组件将显示在“概要”窗口中。您可以在此组件的 items 属性中查看绑定。要将选项添加到列表，请右键单击组件，然后从弹出式菜单中选择“配置缺省选项”。或者，您也可以将如下所示的代码添加到 init() 方法中：

代码样例 1：初始化列表选项

dropDown1DefaultOptions.setOptions(new Option[] {
  new Option("item1", "Item 1"),
  new Option("item2", "Item 2"),
  new Option("item3", "Item 3")}
);

将 items 属性绑定到数据提供器。将数据库表从“服务器”窗口拖放到页面上，以便为表创建数据提供器。接下来，右键单击该组件，从弹出式菜单中选择“绑定到数据”，单击“绑定到数据提供器”标签，然后从现有数据提供器列表中进行选择。选择一列作为返回值，选择另一列作为显示值。
将 items 属性绑定到 com.sun.webui.jsf.model.Option 数组（对于捆绑的 JavaServer Faces 1.1 组件，请使用 com.sun.rave.web.ui.model.Option）。通常，将此数组创建为会话 Bean 属性。如果映射的值为 Option 的实例，则也可以将该属性绑定到用于实现 java.util.Map 的对象。但是，键将被忽略，而且您无法控制显示值的顺序。即，Web 应用程序会随机地显示值。

预先选择项的一种方法是：从 prerender() 方法中调用 setSelected(Object[]) 或 setSelected(Object)。这将传入您要预先选择的项的返回值。在设置缺省选项之前，请确保验证 getSelected() 返回空值，否则在传回时将覆盖用户的选择。

如果将选择组件绑定到缺省选项组件，则可以通过从选择组件的弹出式菜单中选择“配置缺省选项”来预先选择项。请选中“选择项”复选框，然后选择要预先选择的缺省选项。

警告：添加删除列表组件的 Javadoc 和代码完成将显示 getSelectedItems() 方法，该方法会返回一个 Iterator。请不要使用此方法，因为它仅供内部呈现使用，并不反映实际所选的项。

复选框和单选按钮单个复选框和单选按钮组件可以添加到表组件列中。您也可以将复选框和单选按钮组件作为独立的组件添加到页面上。但是，如果要显示可选中选项的列表，则首选单选按钮组和复选框组组件。

日历

使用日历组件，页面访问者可以通过键入日期或从弹出式日历中选择日期来输入日期。selectedDate 属性值包含作为 java.util.Date 对象的输入日期。

要设置弹出式日历的日期范围，请将 minDate 和 maxDate 属性绑定到类型为 java.util.Date 的 Bean 属性（它们具有开始日期和结束日期的值）。以下样例显示了将最小日期设置为当前日期的代码。请注意，对于最小日期，必须将时间设置为 0。

代码样例 2：最小日期属性

    private Date minCalDate;

    public Date getMinCalDate() {
        java.util.Calendar date =
		  java.util.Calendar.getInstance(
		  FacesContext.getCurrentInstance().
		    getViewRoot().getLocale());
        // Have to zero out the time because
        // the date comparison is time sensitive
        date.set(java.util.Calendar.HOUR_OF_DAY, 0);
        date.set(java.util.Calendar.MINUTE, 0);
        date.set(java.util.Calendar.SECOND, 0);
        date.set(java.util.Calendar.MILLISECOND, 0);
        return date.getTime();
    }

在此版本的 Visual Web Pack 中，如果未设置 minimumDate 属性，则最小日期缺省为从当天起 100 年前，而 maximumDate 缺省为从当天起 100 年后。

日期格式缺省为语言环境的缺省格式。您可以使用 dateFormatPattern 属性编辑器从日期格式模式列表中进行选择。

要更改在组件的输入字段下面显示的日期格式模式，请编辑 dateFormatPatternHelp 属性。

提示：可通过将定制错误消息作为 String 传递给组件的 validatorMessage 方法，以覆盖最小和最大日期错误消息。

文件上载

使用文件上载组件，页面访问者可以查找其系统上的文件并将该文件上载到服务器。

对于 JavaServer Faces 1.2 组件，组件的 uploadedFile 属性返回类型为 com.sun.webui.model.UploadedFile 的值；对于 JavaServer Faces 1.1 组件，则返回类型为 com.sun.rave.web.ui.model.UploadedFile 的值。UploadedFile 接口具有多种方法，用于获取文件的名称和大小、确定文件的 MIME 类型（如 text/plain 或 image/jpeg）、按字节或按 String 获取文件的内容，并且可以将内容写入磁盘。要了解详细信息，请在 Java 源代码中右键单击声明语句中的 UploadedFile，然后从弹出式菜单中选择“显示 Javadoc”。

缺省情况下，应用程序将上载文件的大小限制为 1 MB。要更改大小限制，请在应用程序的 web.xml 文件中修改 UploadFilter 过滤器的 maxSize 参数。

定制输入组件的行为和外观

Visual Web Pack 提供了以下功能来定制输入组件的行为和外观。

标记字段。标记输入组件有以下两种方法：
- 使用标签属性。通过设置输入组件的 label 和 labelLevel 属性，可以快速添加标签。在设置标签属性时，组件在标准转换器错误消息、必需错误消息以及验证器错误消息中使用标签值，而不是使用组件 id。
- 使用标签组件。与标签属性相比，标签组件提供了更多的样式控制。此外，您还可以单独地排列标签，不与输入组件对齐，而且可以对标签及其关联输入组件的大小具有更多的控制。使用标签组件而不使用标签属性的一个缺点是，如果未设置标签属性，则错误消息将显示组件的内部 id。您可以通过以下两种方法来覆盖标准错误消息：调用组件的 converterMessage、requiredMessage 以及 validatorMessage 方法以使用定制消息进行覆盖，或者添加资源包以在应用程序范围内覆盖标准消息。
显示错误消息。如前面所述，您可以添加消息和消息组组件以报告转换和验证错误。要将消息组件与输入组件关联，请将消息组件的 for 属性设置为输入组件的 id 属性的值。除非您将消息组组件的 showGlobalOnly 属性设置为 true，否则消息组组件将显示所有的输入转换和输入验证错误消息。
提示：在每个页面添加消息组组件是一种诊断编程错误的很好的方法。
禁用输入并将输入组件设置为具有只读属性。所有输入组件都具有 disabled 和 readOnly 属性。将组件的 disabled 属性设置为 true，可防止用户通过按 Tab 键移动至该组件，并防止应用程序转换、验证和提交值。将组件的 readOnly 属性设置为 true，可防止用户输入或更改该组件的值，但应用程序仍可以转换、验证和提交其值。
设置 Tab 键顺序。使用 tabIndex 属性可以指定用户使用 Tab 键在页面上的输入组件中移动的顺序。
删除空白字符。当输入组件的 trim 属性为 true 时，应用程序将从其输入中删除所有的前导空格和结尾空格。此删除操作将在转换和验证之前执行。一些输入组件（如日历组件和文件上载组件）没有 trim 属性。应用程序将自动从其输入内容中删除这些空格。
限制可以输入的字符数。使用 maxLength 属性可以设置页面访问者可在输入字段中键入的最大字符数。应用程序将忽略后续输入的字符。例如，如果 maxLength 的值是 5，而页面访问者键入了 bicycle，则在字段中显示的全部内容是 bicyc。
使用输入组件提交页。对于大多数输入组件，可以从其弹出式菜单中选择“更改时自动提交”，这样在输入值发生更改时浏览器便会提交页。此功能的一个典型用法是：每当页面访问者从主要数据的下拉列表中选择一个新项时都提交页，这样就可以同步详细数据以匹配新的主要数据选择。例如，当页面访问者从下拉列表中选择一个新产品时，页面将重新显示该产品的详细数据。
如果您不希望浏览器在组件值更改时提交所有输入值，请使用虚拟表单来指定要提交的值。

获取和设置输入值

下表显示了每个输入组件的包含值的属性。使用包含值的属性的 getter 和 setter 方法可以访问输入值。例如，使用 getSelected 和 setSelected 可以获取和设置将 selected 作为其包含值属性的任何组件的输入值。您还可以将这些包含值的属性绑定到数据，如常规信息部分所述。

组件	包含值的属性	类型	注意事项
文本字段、文本区域、口令字段	`text`	`String`，或字段绑定的对象类型（如果已绑定）。
下拉列表	`selected`	对于 `items` 属性，为下拉列表中的每项指定显示标签和返回值。`selected` 属性返回与返回值类型相同的对象。如果使用缺省选项组件指定项和返回值，则 `selected` 属性将返回 `String`。	当页面访问者从下拉列表中选择项时，应用程序将组件的 `selected` 属性设置为选定列表项的返回值。
列表框	`selected`	对于 `items` 属性，为列表中的每项指定显示标签和返回值。`selected` 属性返回对象，或者在选中 `multiple` 属性时，返回与返回值类型相同的对象数组。如果使用缺省选项组件指定项和返回值，则 `selected` 属性将返回 `String`，或者在 `multiple` 属性为 true 时，返回 `String` 对象数组。	如果 `multiple` 属性为 `false`，则组件的 `selected` 属性的值与选定列表项的返回值匹配。如果 `multiple` 属性设置为 `true`（允许用户选择多个项），则必须将 `selected` 属性绑定到 Object 数组、基元数组或 `java.util.List`。如果使用 `java.util.List`，则必须为列表成员的类型指定转换器，除非这些成员是 `String` 对象。数组包含与选定项的返回值匹配的值。
单选按钮（不属于组）	`selected`	缺省情况下，类型为 `boolean`。但是，您可以绑定到诸如 `Boolean`、`Byte`、`Character`、`Double`、`Float`、`Integer`、`Long`、`Short`、`String` 之类的包装器类型，绑定到其中一种包装器类型的基元形式，或绑定到应用程序定义的对象值。	如果组件的 `selected` 属性的值与 `selectedValue` 属性的值匹配，则认为已选中该组件。缺省情况下，`selectedValue` 设置为 `true`。如果几个单选按钮组件具有相同的 `name` 属性值，则每次只能选择集合中的一个单选按钮。当“表组件”列中包含单选按钮组件时，您通常会使用 `name` 属性。
单选按钮组	`selected`	对于 `items` 属性，为每个单选按钮指定显示标签和返回值。`selected` 属性返回与返回值类型相同的对象。如果使用缺省选项组件指定项和返回值，则 `selected` 属性将返回 `String`。	当页面访问者选择单选按钮时，应用程序将单选按钮组的 `selected` 属性设置为选定单选按钮的返回值。
复选框（不属于组）	`selected`	缺省情况下，类型为 `boolean`。但是，您可以绑定到诸如 `Boolean`、`Byte`、`Character`、`Double`、`Float`、`Integer`、`Long`、`Short`、`String` 之类的包装器类型，绑定到其中一种包装器类型的基元形式，或绑定到应用程序定义的对象值。	如果组件的 `selected` 属性的值与 `selectedValue` 属性的值匹配，则认为已选中该组件。缺省情况下，`selectedValue` 设置为 `true`。对于 JavaServer Faces 1.2 版本，如果复选框位于表组件中，请设置 `name` 属性并将 `selectedValue` 绑定到一个属性，getter 将为其返回用于标识复选框的值。例如，让 getter 返回 `tableRowGroup1.getRowKey().toString()`。要确定选中了哪个复选框，请调用复选框组件的 `getSelected` 方法，它将返回一个 `ArrayList`。
复选框组	`selected`	对于 `items` 属性，指定显示标签和返回值。`selected` 值返回与返回值类型相同的对象数组。如果使用缺省选项组件指定项和返回值，则 `selected` 属性将返回 `String` 对象数组。	`selected` 数组中的值与选中复选框的返回值匹配。
日历	`selectedDate`	`java.util.Date`
文件上载	`uploadedFile`	`com.sun.rave.web.ui.model.UploadedFile`	出于安全考虑，`uploadedFile` 属性是只读的。 `UploadedFile` 接口具有多种方法，用于获取文件的名称和大小、按 `String` 类型获取文件的内容，并将内容写入磁盘。要了解详细信息，请在 Java 源代码中右键单击声明语句中的 `UploadedFile`，然后从弹出式菜单中选择“显示 Javadoc”。 `UploadedFile.getOriginalName()` 方法将返回客户端文件系统中的原始文件名，该名称由浏览器提供。在大多数情况下，这是基本文件名，不包含路径信息。但是，部分浏览器包含路径信息。注意：各种浏览器会以不同的方式呈现文件上载组件。通常，在浏览器中显示的组件要比在可视设计器中显示得小。
添加删除列表	`selected`	`Object` 数组	对于 `items` 属性，指定显示标签和返回值。`selected` 数组中的值与选定项的返回值匹配。

验证用户输入

您可以使用以下功能来验证用户输入。当一个或多个输入字段验证失败时，Web 应用程序将重新呈现页面，以红色突出显示无效输入的关联标签（如果存在），并将错误消息发送到消息组组件和关联的消息组件（如果它们存在于页面上）。

必需的输入。每个输入组件都提供了一个 required 属性。当该属性设置为 true 时，Web 应用程序将自动验证输入是否具有值。
值转换。如常规信息部分所述，Visual Web Pack 提供了一些可应用于输入组件的转换器。转换在验证过程开始之前执行。如果页面访问者提供了应用程序无法将其转换为指定数据类型的值，则 Web 应用程序将拒绝所输入的内容并发送一条错误消息。此错误消息显示在消息组组件和关联的消息组件（如果它们存在于页面上）中。数值转换器是一种非常有用的转换器，您可以使用它来指定输入内容必须匹配的模式。
输入验证。Visual Web Pack 提供了三种可以应用于任何输入组件的验证组件：
- 双精度范围验证器。检查组件的转换值是否在某个范围内。该值必须是浮点型或者可以转换为浮点型。
- 长度验证器。检查组件的本地值的长度是否在某个范围内。该值必须是 String。
- 长型范围验证器。检查组件的本地值是否在某个范围内。该值必须为任何数值类型或可以转换为 long 型的 String。
此外，您可以通过右键单击组件并选择“编辑事件处理程序”> "Validate" 来添加自己的验证方法。此菜单项将创建一种验证方法，并将该方法注册为验证事件侦听程序。该验证方法接受 FacesContext、UIComponent 和 Object（值），并抛出 ValidatorException。

与转换错误一样，应用程序也将验证错误消息发送到消息组组件和关联的消息组件（如果它们存在于页面上）。

注意：您可以将验证器应用于组件，也可以为组件注册验证事件处理程序，但不能同时执行这两种操作。
Web 应用程序在调用任何值更改侦听程序和操作侦听程序之前执行所有验证。如果出现一个或多个验证错误，则不调用值更改侦听程序和操作侦听程序，而且 Web 应用程序将重新呈现页面，以便页面访问者可以更正问题。
更改时立即处理。如果希望浏览器在页面访问者更改组件的值后立即提交页面，请右键单击组件，然后从弹出式菜单中选择“更改时自动提交”。
停用转换和验证。有时您可能希望停止对页面上的某些输入组件进行处理（其中包括转换和验证），可以使用 IDE 的虚拟表单设置来指定给定操作可处理哪些字段。例如，当页面访问者单击“取消”按钮时，可能希望绕过对所有输入字段的处理。或者，页面上可能有两个按钮，并且您仅希望根据被单击的按钮来提交字段的子集。
请注意，您也可以使用 immediate 属性来限制对输入值的处理。但是，虚拟表单的功能更易于使用。例如，对于在早于其他组件的 JavaServer Faces 生命周期阶段中将其 immediate 属性设置为 true 的组件，Web 应用程序将调用其转换、验证和值更改侦听程序（如果是操作组件，则调用操作侦听程序）。也就是说，在出现常规转换过程之前和在后续进程验证阶段中出现验证之前，将在应用请求值阶段中对 immediate 属性设置为 true 的组件调用这些处理步骤。相反，虚拟表单要简单得多，因为它们不改变 JavaServer Faces 生命周期。

当页面访问者提交页时，Web 应用程序将按以下顺序执行输入内容的验证：

转换
必需的输入
验证

注意：仅当实际发生值更改且所有验证都成功时，才会出现值更改事件。

处理值更改事件

当输入组件的验证成功且提交的值与显示的值不同时，使用 Visual Web Pack 生成的 Web 应用程序将为该输入组件发送值更改事件。您可以将一个方法注册为值更改事件处理程序，用于响应此类事件。例如，您可以编写一个在用户更改主要值时更改详细数据的方法，然后将该方法注册为值更改侦听程序。当页面访问者更改了主要值并提交页时，Web 应用程序将调用该方法，这样就可以更新要匹配的详细数据。

应用程序按以下顺序引发事件：

首先引发 immediate 属性设置为 true 的组件的事件（按照深度优先的原则遍历组件树）。
然后引发 immediate 属性未设置为 true 的输入组件的值更改事件（按照深度优先的原则遍历组件树）。
最后引发 immediate 属性未设置为 true 的命令组件的操作事件（按照深度优先的原则遍历组件树）。

创建和注册值更改事件处理程序的一种快速方法是：在可视设计器中双击输入组件。执行此操作时，IDE 将创建一个方法，并将该方法注册为组件的值更改事件侦听程序。组件的 valueChange 属性将显示已注册的事件处理程序的名称（如果存在）。

操作和链接组件

使用操作和链接组件可以让页面访问者从一个页面移动至下一个页面并提交输入的内容。下图显示了组件面板所提供的操作和链接组件。

图 7：操作和链接组件

简单页面导航

如果您希望用户通过单击组件移动至特定的页面，但不希望浏览器提交任何用户输入，则可以使用超级链接组件、图像超级链接组件、标签组件或树节点组件，并在组件的 url 属性中键入目标页的路径，如 /faces/Page1.jsp。

动态页面导航

通过页面导航编辑器，您可以指定将用户操作和决策逻辑结果映射到目标页的导航规则。通过将一条已命名的连线从链接或操作组件拖动到目标页，可以指定映射。您还必须为返回结果（此结果为等于连线名称的 String 值）的组件创建操作处理程序。您可以使用组件的 action 属性来创建操作处理程序。

当页面访问者单击组件时，浏览器将提交输入（如果存在），而且操作处理程序返回结果。服务器在导航规则映射中查找结果，以确定用于响应的页。如果该结果没有导航规则，则服务器将重新显示当前页。您可以编写操作处理程序，使其根据业务逻辑返回不同的结果。

注意：当您同时设置了 url 和 action 属性时，将优先采用 url 处理程序，而不会调用 action 处理程序。

有关页面导航的详细信息，请参见设置页面导航教程。

布局组件

组件面板包含一些布局组件，用于帮助您在页面上排列组件以及采用有效的方式显示组件，如下图所示。

图 8：布局组件

下表说明了每个布局组件的用途，并描述了如何使用各个组件。

组件用法

Breadcrumbs

通过 Breadcrumbs 组件，您可以布置由右尖括号 (>) 分隔的一系列链接组件。通常，您可以使用 Breadcrumbs 组件向页面访问者显示页面所在部分或分支的分层结构。当您添加 Breadcrumbs 组件时，IDE 将自动为应用程序中的每个页面添加一个嵌套的超级链接组件。您可以使用“概要”窗口来删除、添加和重新排列嵌套的超级链接组件。

或者，您也可以将 pages 属性绑定到 Hyperlink 对象数组，其中每个超级链接都表示一页。为确保正确显示，每个超级链接组件都必须至少具有一个 text 属性的值以及一个 url 属性或 action 属性的值。

页面片段框

通过页面片段框组件，您可以跨越若干页重用同一内容。当您更改页面片段的内容时，所做的更改将出现在使用该页面片段的所有页上。

页面分隔符

使用页面分隔符组件可以创建用于分隔页面上各项的水平线。您还可以使用页面分隔符组件来分隔网格面板单元格或组面板组件中的各项。

树和树节点

使用树组件和嵌套的树节点组件可以采用树状结构呈现可展开的列表。树通常用于 Web 应用程序中的导航以及在嵌套数据（如文件系统结构）中的导航。要添加其他节点，请右键单击“概要”窗口中的树组件或树节点组件，然后选择“添加树节点”。节点的缺省图像是文件夹图标或页面图标，具体取决于该节点是否具有子节点（嵌套节点）。

使用 action 属性可以指定页面访问者选择树节点时的操作处理程序。使用 actionListener 属性可以指定页面访问者打开或关闭节点时的处理程序。

提示：缺省情况下，每次页面访问者展开或折叠节点时，浏览器都会向服务器发出请求。要将展开和折叠操作发生在客户端上，请将 clientSide 设置为 true。

标签集和标签

您可以将标签集组件用作导航工具，或者也可以使用它来显示同一页上的不同布局。要添加标签，请右键单击“概要”窗口中的标签集节点，然后选择“添加标签”。

要将标签集组件用作导航工具，请为每个导航路径添加一个标签，然后使用页面导航编辑器指定每个标签的目标页。

要使用标签集组件显示同一页上的不同布局，请添加所需数目的标签。然后，在可视设计器中选择每个标签，并添加该标签的组件。

标签集组件的 selected 属性显示当前选定标签的 id。
标签组件包含嵌套的布局面板组件。要将组件添加到标签，请将这些组件拖放到布局面板组件中。

布局面板

此面板类似于一个页面，因为通过设置布局面板组件的 layoutPanel 值可以指定网格布局或流布局。在流模式下，组件从左到右排列。在网格模式下，组件将按照您拖放它们的位置定位。

属性表单和属性

通过属性表单组件，您可以快速布置一组带标签的组件。属性表单组件可提供并布置标签和类别，您所做的就是添加组件。要添加类别，请右键单击属性表单节点，然后选择“添加属性表单类别”。要添加属性，请右键单击类别节点，然后选择“添加属性”。要将组件添加到属性，请将组件从组件面板拖放到“概要”窗口中的属性节点上。

要在属性表单的顶部显示指向每个类别的链接，请将属性表单组件的 jumpLinks 设置为 true。您可以使用属性组件的 labelAlign 属性将标签左对齐或右对齐。如果不希望标签文本换行，请将 noWrap 设置为 true。

网格面板

使用网格面板组件可以按行和按列排列组件。在将网格面板组件添加到页面后，请将其 columns 属性设置为每行的列数。当您将组件添加到网格面板组件时，IDE 会跨行添加组件，直到填满行为止。IDE 将根据需要添加行。

组面板

使用组面板组件可以在流布局模式下组合嵌套组件。浏览器以彼此相邻的方式放置组件，并根据需要将组件自动换到下一行。当页面访问者调整页面大小时，组件会上移一行或下移一行。组面板组件对于嵌套组件（如在页面警报组件内嵌套按钮组件或在网格面板组件的单元格内嵌套组件）是非常有用的。

缺省情况下，block 属性设置为 false，这意味着将使用 <span> 标记呈现组件，并忽略高度和宽度样式设置。如果需要为组件设置特定的高度或宽度，请将 block 属性设置为 true。
如果页面处于流布局模式，则将 block 属性设置为 true 会使浏览器将组件呈现在它自己单独的行上。该组件前后的组件则出现在其他行上。

表

使用表组件，可以轻松地显示表格数据，如数据库表中的数据或者数组或列表中的信息。填充表组件的最快速方法是：为表格数据创建数据提供器，然后将表组件绑定到该数据提供器，如使用数据绑定组件访问数据库教程中所示。

右键单击表组件，然后选择“表布局”，将显示一个对话框，您可以通过该对话框执行以下操作：

设置表的标题

添加和删除列

设置每列的标题、脚注和组件类型（如静态文本、文本字段或按钮）

启用排序和添加各种排序按钮

启用分页

指定单元格为空时应该显示的文本

使用表的嵌套 TableRowGroup 组件可以处理表的数据值。例如，如果列具有一个按钮，则使用 TableRowGroup 组件的 getRowKey() 可以确定数据的基础行，如下面的代码样例所示。

代码样例 3：处理表中的按钮

public String submitTableButton_action() { RowKey rowkey = tableRowGroup1.getRowKey(); getSessionBean1().setSelectedPersonId( travelDataProvider.getValue("PERSON.PERSONID", rowkey).toString()); return "showDetail"; }

提示：在可视设计器中使用嵌套组件时，按 Esc 键可以选择其包含（父）组件。您还可以使用“概要”窗口来选择包含父组件以及重新排列嵌套组件的顺序。

非可视组件

Visual Web Pack 提供了两种非可视组件。

组件	用法
隐藏字段	隐藏字段组件是非可视表单字段。隐藏字段组件的典型用法是存储值以供 JavaScript 使用。由于提交了隐藏字段组件的值，因此服务器端代码（如页面 Bean）可以检查 JavaScript 代码执行的更改。您还可以使用隐藏字段组件将值传递到重新呈现的页面。
锚点	使用锚点组件可以在页面内放置链接目标。锚点组件相当于 HTML `<a name=`targetname>。该组件的 id 是目标名称。例如，如果锚点组件的 id 是 `anchor1`，则可以将超级链接的 `url` 属性设置为 `#anchor1` 以跳转到该锚点组件的位置。