JSF标签

原文：http://www.javaworld.com.tw/confluence/pages/viewpage.action?pageId=2630

繁简转换与修订：jnzgy@163.com

声明：为方便简体中文读者阅读，特将原文转换为简体，对一些习惯用语做了替换，同时对部分内容
做了修订。版权归原文作者所有，未经许可，不得用于商业目的。

2006年3月27日

1. 标签入门.....................................................................................................................................2
1.1 简介JSF标准标签............................................................................................................2
1.2 输出类标签........................................................................................................................3
1.3 输入类标签........................................................................................................................4
1.4 命令类标签........................................................................................................................4
1.5 选择类标签 一..................................................................................................................5
1.6 选择类标签 二..................................................................................................................7
1.7 其它标签............................................................................................................................9
2. 表格处理...................................................................................................................................11
2.1 简单的表格......................................................................................................................11
2.2 表头、表尾......................................................................................................................14
2.3 TableModel类..................................................................................................................16

网页设计人员要做的就是了解JSF的标签的使用方式，这就像是学习进阶的
HTML标签，另一件事就是与程序设计人员沟通好各个Bean的名称绑定。

1. 标签入门

标签的相关属性查询，您可以参考 Tag Library Documentation，这边的介
绍只是一些简单的入门实例。

1.1 简介JSF标准标签

 JSF提供了标准的HTML Renderer Kit，可以让您搭配JSF组件输出HTML文件，
标准的HTML Renderer Kit主要包括了几个类别：

.. 输出（Outputs）

 其名称以output作为开头，作用为输出指定的信息或绑定值。

.. 输入（Inputs）

 其名称以input作为开头，其作用为提供使用者输入框。

.. 命令（Commands）

 其名称以command作为开头，其作用为提供命令或链接按钮。

.. 选择（Selections）

 其名称以select作为开头，其作用为提供使用者选项的选取。

.. 其它

 包括了form、message、messages、graphicImage等等未分类的标签。

 JSF标准HTML标签包括了几个共通的属性，整理如下：

属性名称

适用

说明

id

所有组件

可指定id名称，以让其它标签或组件
参考

binding

所有组件

绑定至UIComponent

rendered

所有组件

是否显示组件

styleClass

所有组件

设定Cascading stylesheet(CSS)

value

输入、输出、命
令组件

设定值或绑定至指定的值

valueChangeListener

输入组件

设定值变事件处理者

converter

输入、输出组件

设定转换器

validator

输入组件

设定验证器

required

输入组件

是否验证必填输入框

immediate

输入、命令组件

是否为即时事件

 除了共通的属性之外，您还可以在某些组件上设定标签HTML 4.01的属性，
像是size、alt、width等属性，或者是设定DHTML事件属性，例如onchange、onclick
等等。

 除了JSF的标准HTML标签之外，您还需要一些标准核心标签，这些标签是独
立于Renderer Kit的，JSF并不限制在HTML输出表示层，核心标签可以搭配其它

的Renderer Kit来使用。

详细的HTML标签或核心标签的使用与属性说明可以查询 Tag Library
Documentation 文件

1.2 输出类标签

 输出类的标签包括了outputLabel、outputLink、outputFormat与
outputText，分别举例说明如下：

.. outputLabel

 产生<label> HTML标签，使用for属性指定组件的client ID，例如：

<h:inputText id="user" value="#{user.name}"/>

<h:outputLabel for="user" value="#{user.name}"/>

 这会产生像是以下的标签：

<input id="user" type="text" name="user" value="guest" />

<label for="user">

.. outputLink

 产生<a> HTML标签，例如：

<h:outputLink value="../index.jsp">

 <h:outputText value="Link to Index"/>

 <f:param name="name" value="MyName"/>

</h:outputLink>

 你可搭配<f:param>帮链结加上参数，所有的参数都会变成 name=value 的
类型附加在链接后。

 value所指定的内容也可以是JSF EL绑定。

.. outputFormat

 产生指定的文字信息，可以搭配<f:param>来设定信息的参数以格式化文字
信息，例如：

<f:loadBundle basename="messages" var="msgs"/>

 <h:outputFormat value="#{msgs.welcomeText}">

 <f:param value="Hello"/>

 <f:param value="Guest"/>

 </h:outputFormat>

 如果您的messages.properties包括以下的内容：

welcomeText={0}, Your name is {1}.

 则{0}与{1}会被取代为<f:param>设定的文字，最后显示的文字会是：

Hello, Your name is Guest.

 另一个使用的方法则是：

<h:outputFormat value="{0}, Your name is {1}.">

 <f:param value="Hello"/>

 <f:param value="Guest"/>

 </h:outputFormat>

.. outputText

 简单的显示指定的值或绑定的信息，例如：

<h:outputText value="#{user.name}"/>

1.3 输入类标签

 输入类标签包括了inputText、inputTextarea、inputSecret、 inputHidden，
分别举例说明如下：

.. inputText

 显示单行输入框，即输出<input> HTML标签，其type属性设定为text，例如：

<h:inputText value="#{user.name}"/>

.. inputTextarea

 显示多行输入文字区域，即输出<textarea> HTML标签，例如：

<h:inputTextarea value="#{user.command}"/>

.. inputSecret

 显示密码输入框，即输出<input> HTML标签，其type属性设定为password，
例如：

<h:inputSecret value="#{user.password}"/>

 您可以设定redisplay属性以决定是否要显示密码栏目的值，预设是false。

.. inputHidden

 隐藏输入框，即输出<input> HTML标签，其type属性设定为hidden，隐藏输
入框的值用于保留一些信息于客户端，以在下一次发送表单时一并提交，例如：

<h:inputHidden value="#{user.hiddenInfo}"/>

1.4 命令类标签

 命令类标签包括commandButton与commandLink，其主要作用在于提供一个命
令按钮或链接，以下举例说明：

.. commandButton

 显示一个命令按钮，即输出<input> HTML标签，其type属性可以设定为
button、submit或reset，预设是submit，按下按钮会触发 javax.faces.event.
ActionEvent，使用例子如下：

<h:commandButton value="提交" action="#{user.verify}"/>

 您可以设定image属性，指定图片的URL，设定了image属性的话，<input>
标签的type属性会被设定为image，例如：

<h:commandButton value="#{msgs.commandText}"

 image="images/logowiki.jpg"

 action="#{user.verify}"/>

.. commandLink

 产生超链接，会输出<a> HTML标签，而href属性会有'#'，而onclick属性会
含有一段JavaScript程序，这个JavaScript的目的是按下链接后自动提交表单，
具体来说其作用就像按钮，但外观却是超链接，包括在本体部份的内容都会成为
超链接的一部份，一个使用的例子如下：

<h:commandLink value="#{msgs.commandText}"

 action="#{user.verify}"/>

 产生的HTML输出范例如下：

<a href="#" onclick="document.forms['_id3']['_id3:_idcl'].value='_id3:_id13';
document.forms['_id3'].submit(); return false;">Submit</a>

 如果搭配<f:param>来使用，则所设定的参数会被当作请求参数一并提交，
例如：

<h:commandLink>

 <h:outputText value="welcome"/>

 <f:param name="locale" value="zh_CN"/>

 </h:commandLink>

1.5 选择类标签 一

 选择类的标签可大致分为单选标签与多选标签，依外型的不同可以分为单选
钮（Radio）、复选框（CheckBox）、列表框（ListBox）与菜单（Menu），以下
分别先作简单的说明。

.. <h:selectBooleanCheckbox>

 在视图上呈现一个复选框，例如：

我同意 <h:selectBooleanCheckbox value="#\{user.aggree\}"/>

 value所绑定的属性必须接受与传回boolean类型。这个组件在网页上呈现的
外观如下：

.. <h:selectOneRadio>、<h:selectOneListbox>、<h: selectOneMenu>

 这三个标签的作用，是让使用者从其所提供的选项中选择一个项目，所不同
的就是其外观上的差别，例如：

<h:selectOneRadio value="#{user.education}">

 <f:selectItem itemLabel="高中" itemValue="高中"/>

 <f:selectItem itemLabel="大学" itemValue="大学"/>

 <f:selectItem itemLabel="研究所以上" itemValue="研究所以上"/>

 </h:selectOneRadio><p>

 value所绑定的属性可以接受字符串以外的类型或是自定义类型，但记得如
果是必须转换的类型或自定义类型，必须搭配 标准转换器 或 自定义转换器 来
转换为对象，<h:selectOneRadio>的外观如下：

 您也可以设定layout属性，可设定的属性是lineDirection、pageDirection，
预设是lineDirection，也就是由左到右来排列选项，如果设定为pageDirection，
则是由上至下排列选项，例如设定为：

<h:selectOneRadio layout="pageDirection"

 value="#{user.education}">

 <f:selectItem itemLabel="高中" itemValue="高中"/>

 <f:selectItem itemLabel="大学" itemValue="大学"/>

 <f:selectItem itemLabel="研究所以上" itemValue="研究所以上"/>

 </h:selectOneRadio><p>

 则外观如下：

 <h:selectOneListbox>、<h:selectOneMenu>的设定方法类似于<h:
selectOneRadio>，以下分别列出<h:selectOneListbox>、<h: selectOneMenu>
的外观：

.. <h:selectManyCheckbox>、<h:selectManyListbox>、<h: selectManyMenu>

 这三个标签提供使用者复选项目的功能，一个<h:selectManyCheckbox>例子
如下：

<h:selectManyCheckbox layout="pageDirection"

 value="#{user.preferColors}">

 <f:selectItem itemLabel="红" itemValue="false"/>

 <f:selectItem itemLabel="黄" itemValue="false"/>

 <f:selectItem itemLabel="蓝" itemValue="false"/>

 </h:selectManyCheckbox><p>

 value所绑定的属性必须是列表或集合（Collection）对象，在这个例子中
所使用的是boolean列表，例如：

. UserBean.java

package onlyfun.caterpillar;

 public class UserBean {

 private boolean[] preferColors;

 public boolean[] getPreferColors() {

 return preferColors;

 }

 public void setPreferColors(boolean[] preferColors) {

 this.preferColors = preferColors;

 }

 ......

 }

 如果是其它类型的对象，必要时必须搭配转换器（Converter）进行字符串
与对象之间的转换。

 下图是<h:selectManyCheckbox>的外观，这是将layout设定为
pageDirection的外观：

 <h:selectManyListbox>的设定方法类似，其外观如下：

 <h:selectManyMenu>在不同的浏览器中会有不同的外观，在Mozilla
Firefox中是这样的：

 在Internet Explorer则是这样的：

1.6 选择类标签 二

 选择类标签可以搭配<f:selectItem>或<f:selectItems>标签来设定选项，例
如：

<f:selectItem itemLabel="高中"

 itemValue="高中"

 itemDescription="学历"

 itemDisabled="true"/>

 itemLabel属性设定显示在网页上的文字，itemValue设定发送至伺服端时的
值，itemDescription 设定文字描述，它只作用于一些工具程序，对HTML没有什
么影响，itemDisabled设定是否选项是否作用，这些属性也都可以使用JSF
Expression Language来绑定至一个值。

 <f:selectItem>也可以使用value来绑定一个传回javax.faces.model.
SelectItem的方法，例如：

<f:selectItem value="#{user.sex}"/>

 则绑定的Bean上必须提供下面这个方法：

....

 public SelectItem getSex() {

 return new SelectItem("男");

 }

 ....

 如果要一次提供多个选项，则可以使用<f:selectItems>，它的value绑定至

一个提供传回SelectItem的列表、集合，或者是Map对象的方法，例如：

<h:selectOneRadio value="#{user.education}">

 <f:selectItems value="#{user.educationItems}"/>

 </h:selectOneRadio><p>

 这个例子中<f:selectItems>的value绑定至user.educationItems，其内容
如下：

....

 private SelectItem[] educationItems;

 public SelectItem[] getEducationItems() {

 if(educationItems == null) {

 educationItems = new SelectItem[3];

 educationItems[0] =

 new SelectItem("高中", "高中");

 educationItems[1] =

 new SelectItem("大学", "大学");

 educationItems[2] =

 new SelectItem("研究所以上", "研究所以上");

 }

 return educationItems;

 }

 ....

 在这个例子中，SelectItem的第一个构造参数用以设定value，而第二个参
数用以设定label，SelectItem还提供有数个构造函数，记得可以参考一下联机
API文件。

 您也可以提供一个传回Map对象的方法，Map的key-value会分别作为选项的
label-value，例如：

<h:selectManyCheckbox layout="pageDirection"

 value="#{user.preferColors}">

 <f:selectItems value="#{user.preferColorItems}"/>

 </h:selectManyCheckbox><p>

 您要提供下面的程序来搭配上面这个例子：

....

 private Map preferColorItems;

 public Map getPreferColorItems() {

 if(preferColorItems == null) {

 preferColorItems = new HashMap();

 preferColorItems.put("红", "Red");

 preferColorItems.put("黄", "Yellow");

 preferColorItems.put("蓝", "Blue");

 }

 return preferColorItems;

 }

 ....

1.7 其它标签

 <h:messages>或<h:message>标签的介绍，在 错误信息处理 中已经有介绍了。

.. <h:graphicImage>

 这个标签会绘制一个HTML <img>标签，value可以指定路径或图片URL，路径
可以指定相对路径或绝对路径，例如：

<h:graphicImage value="/images/logowiki.jpg"/>

.. <h:panelGrid>

 这个标签可以用来作简单的组件排版，它会使用HTML表格标签来绘制表格，
并将组件置于其中，主要指定columns属性，例如设定为 2：

<h:panelGrid columns="2">

 <h:outputText value="Username"/>

 <h:inputText id="name" value="#{userBean.name}"/>

 <h:outputText value="Password"/>

 <h:inputText id="password" value="#{userBean.password}"/>

 <h:commandButton value="submit" action="login"/>

 <h:commandButton value="reset" type="reset"/>

 </h:panelGrid>

 则自动将组件分作 2 个 column来排列，排列出来的样子如下：

 <h:panelGrid>的本体间只能包括JSF组件，如果想要放入非JSF组件，例如
简单的样版（template）文字，则要使用 <f:verbatim>包括住，例如：

<h:panelGrid columns="2">

 <f:verbatim>Username</f:verbatim>

 <h:inputText id="name" value="#{userBean.name}"/>

 <f:verbatim>Password</f:verbatim>

 <h:inputText id="password" value="#{userBean.password}"/>

 <h:commandButton value="submit" action="login"/>

 <h:commandButton value="reset" type="reset"/>

 </h:panelGrid>

.. <h:panelGroup>

 这个组件用来将数个JSF组件包装起来，使其看来像是一个组件，例如：

<h:panelGrid columns="2">

 <h:outputText value="Username"/>

 <h:inputText id="name" value="#{userBean.name}"/>

 <h:outputText value="Password"/>

 <h:inputText id="password" value="#{userBean.password}"/>

 <h:panelGroup>

 <h:commandButton value="submit" action="login"/>

 <h:commandButton value="reset" type="reset"/>

 </h:panelGroup>

 </h:panelGrid>

 在<h:panelGroup>中包括了两个<h:commandButton>，这使得<
h:panelGrid>在处理时，将那两个<h:commandButton>看作是一个组件来看待，
其完成的版面配置如下所示：

2. 表格处理

对于必须使用表格方式呈现的数据，JSF 的 <h:dataTable> 标签协助您进
行动态表格数据的输出。

2.1 简单的表格

 很多数据经常使用表格来表现，JSF提供<h:dataTable>标签让您得以列举数
据并使用表格方式来呈现，举个实际的例子来看，假设您编写了以下的两个类：

. UserBean.java

package onlyfun.caterpillar;

 public class UserBean {

 private String name;

 private String password;

 public UserBean() {

 }

 public UserBean(String name, String password) {

 this.name = name;

 this.password = password;

 }

 public String getName() {

 return name;

 }

 public void setName(String name) {

 this.name = name;

 }

 public String getPassword() {

 return password;

 }

 public void setPassword(String password) {

 this.password = password;

 }

 }

. TableBean.java

package onlyfun.caterpillar;

 import java.util.*;

 public class TableBean {

 private List userList;

 public List getUserList() {

 if(userList == null) {

 userList = new ArrayList();

 userList.add(new UserBean("caterpillar", "123456"));

 userList.add(new UserBean("momor", "654321"));

 userList.add(new UserBean("becky", "7890"));

 }

 return userList;

 }

 }

 在TableBean中，我们假设getUserList()方法实际上是从数据库中查询出
UserBean的内容，之后传回List对象，若我们的 faces-config.xml如下：

. faces-config.xml

<?xml version="1.0" encoding="UTF-8"?>

 <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems,

 Inc.//DTD JavaServer Faces Config 1.0//EN"

 "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">

 <faces-config>

 <managed-bean>

 <managed-bean-name>tableBean</managed-bean-name>

 <managed-bean-class>

 onlyfun.caterpillar.TableBean

 </managed-bean-class>

 <managed-bean-scope>request</managed-bean-scope>

 </managed-bean>

 <managed-bean>

 <managed-bean-name>userBean</managed-bean-name>

 <managed-bean-class>

 onlyfun.caterpillar.UserBean

 </managed-bean-class>

 <managed-bean-scope>request</managed-bean-scope>

 </managed-bean>

 </faces-config>

 我们可以如下使用<h:dataTable>来产生表格数据：

. index.jsp

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>

 <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>

 <html>

 <body>

 <f:view>

 <h:dataTable value="#{tableBean.userList}" var="user">

 <h:column>

 <h:outputText value="#{user.name}"/>

 </h:column>

 <h:column>

 <h:outputText value="#{user.password}"/>

 </h:column>

 </h:dataTable>

 </f:view>

 </body>

 </html>

 <h:dataTable>的value值绑定tableBean的userList方法，它会一个一个取
出 List中的数据并设定给var设定的user，之后在每一个column中我们可以显示
所列举出的user.name与user.password，程序的结果会如下所示：

（注：此处应该有图，但是原文就没有附上。）

 所产生的HTML表格标签如下：

<table>

 <tbody>

 <tr>

 <td>caterpillar</td>

 <td>123456</td>

 </tr>

 <tr>

 <td>momor</td>

 <td>654321</td>

 </tr>

 <tr>

 <td>becky</td>

 <td>7890</td>

 </tr>

 </tbody>

 </table>

 <h:dataTable>的value值绑定的对象可以是以下的类型：

.. 列表

.. java.util.List的实例
.. java.sql.ResultSet的实例
.. javax.servlet.jsp.jstl.sql.Result的实例
.. javax.faces.model.DataModel的实例

2.2 表头、表尾

 <h:dataTable>配合<h:column>来以表格的方式显示数据，< h:column>中只
能包括 JSF组件或者是<f:facet>，JSF支援两种facet：header与footer。分别
用以设定表格的表头与表尾文字，一个设定的例子如下：

<h:dataTable value="#{tableBean.userList}" var="user">

 <h:column>

 <f:facet name="header">

 <h:outputText value="Name"/>

 </f:facet>

 <h:outputText value="#{user.name}"/>

 <f:facet name="footer">

 <h:outputText value="****"/>

 </f:facet>

 </h:column>

 <h:column>

 <f:facet name="header">

 <h:outputText value="Password"/>

 </f:facet>

 <h:outputText value="#{user.password}"/>

 <f:facet name="footer">

 <h:outputText value="****"/>

 </f:facet>

 </h:column>

 </h:dataTable>

 所产生的表格如下所示：

 另外，对于表头、表尾乃至于每一行列，都可以分别设定CSS风格，例如下
面这个styles.css摘录自Core JSF一书：

. styles.css

.orders {

 border: thin solid black;

 }

 .ordersHeader {

 text-align: center;

 font-style: italic;

 color: Snow;

 background: Teal;

 }

 .evenColumn {

 height: 25px;

 text-align: center;

 background: MediumTurquoise;

 }

 .oddColumn {

 text-align: center;

 background: PowderBlue;

 }

 可以在我们的页面中如下加入：

....

 <link href="styles.css" rel="stylesheet" type="text/css"/>

 ....

 <h:dataTable value="#{tableBean.userList}" var="user"

 styleClass="orders"

 headerClass="ordersHeader"

 rowClasses="evenColumn,oddColumn">

 <h:column>

 <f:facet name="header">

 <h:outputText value="Name"/>

 </f:facet>

 <h:outputText value="#{user.name}"/>

 <f:facet name="footer">

 <h:outputText value="****"/>

 </f:facet>

 </h:column>

 <h:column>

 <f:facet name="header">

 <h:outputText value="Password"/>

 </f:facet>

 <h:outputText value="#{user.password}"/>

 <f:facet name="footer">

 <h:outputText value="****"/>

 </f:facet>

 </h:column>

 </h:dataTable>

 则显示的表格结果如下：

2.3 TableModel类

 在 简单的表格 中曾经提过，<h:dataTable>可以列举以下几种类型的数据：

.. 列表
.. java.util.List的实例
.. java.sql.ResultSet的实例
.. javax.servlet.jsp.jstl.sql.Result的实例
.. javax.faces.model.DataModel的实例

 对于前四种类型，JSF实际上是以javax.faces.model.DataModel加以包装，
DataModel是个抽象类，其子类都是位于 javax.faces.model这个package下：

ArrayDataModel

ListDataModel

ResultDataModel

ResultSetDataModel

ScalarDataModel

 如果您想要对表格数据有更多的控制，您可以直接使用DataModel来设定表
格数据，调用DataModel的setWrappedObject()方法可以让您设定对应类型的数
据，调用getWrappedObject()则可以取回数据，例如：

. TableBean.java

package onlyfun.caterpillar;

 import java.util.*;

 import javax.faces.model.DataModel;

 import javax.faces.model.ListDataModel;

 public class TableBean {

 private DataModel model;

 private int rowIndex = -1;

 public DataModel getUsers() {

 if(model == null) {

 model = new ListDataModel();

 model.setWrappedData(getUserList());

 }

 return model;

 }

 private List getUserList() {

 List userList = new ArrayList();

 userList.add(new UserBean("caterpillar", "123456"));

 userList.add(new UserBean("momor", "654321"));

 userList.add(new UserBean("becky", "7890"));

 return userList;

 }

 public int getSelectedRowIndex() {

 return rowIndex;

 }

 public String select() {

 rowIndex = model.getRowIndex();

 return "success";

 }

 }

 在这个Bean中，我们直接设定DataModel，将userList设定给它，如您所看
到的，我们还可以取得DataModel的各个变量，在这个例子中，select()将作为
点选表格之后的事件处理方法，我们可以借由DataModel的getRowIndex()来取得
所点选的是哪一row的数据，例如：

index.jsp

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>

 <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>

 <html>

 <link href="styles.css" rel="stylesheet" type="text/css"/>

 <body>

 <f:view>

 <h:form>

 <h:dataTable value="#{tableBean.users}" var="user"

 styleClass="orders"

 headerClass="ordersHeader"

 rowClasses="evenColumn,oddColumn">

 <h:column>

 <f:facet name="header">

 <h:outputText value="Name"/>

 </f:facet>

 <h:commandLink action="#{tableBean.select}">

 <h:outputText value="#{user.name}"/>

 </h:commandLink>

 <f:facet name="footer">

 <h:outputText value="****"/>

 </f:facet>

 </h:column>

 <h:column>

 <f:facet name="header">

 <h:outputText value="Password"/>

 </f:facet>

 <h:outputText value="#{user.password}"/>

 <f:facet name="footer">

 <h:outputText value="****"/>

 </f:facet>

 </h:column>

 </h:dataTable>

 </h:form>

 Selected Row: <h:outputText

 value="#{tableBean.selectedRowIndex}"/>

 </f:view>

 </body>

 </html>

 DataModel的rowIndex是从0开始计算，当处理ActionEvent时，JSF会逐次递
增rowIndex的值，这让您可以得知目前正在处理的是哪一个row的数据，一个执
行的图示如下：