Question

表单标签库中包含了可以用在 JSP 页面中渲染 HTML 元素的标签。为了使用这些标签，必须在 JSP 页面的开头处声明这个 taglib 指令。

<%@taglib prefix="form"
  uri="http://www.springframework.org/tags/form" %>

表 5.1 展示了表单标签库中的标签。

在接下来的小节中，将逐一介绍这些标签。5.3 节展示了一个范例应用程序，展示了数据绑定结合表单标签库的使用方法。

表 5.1 表单标签库中的标签

标签	描述
form	渲染表单元素
input	渲染<input type="text"/>元素
password	渲染<input type="password"/>元素
hidden	渲染<input type="hidden"/>元素
textarea	渲染 textarea 元素
checkbox	渲染一个<input type="checkbox"/>元素
checkboxes	渲染多个<input type="checkbox"/>元素
radiobutton	渲染一个<input type="radio"/>元素
radiobuttons	渲染多个<input type="radio"/>元素
select	渲染一个选择元素
option	渲染一个可选元素
options	渲染一个可选元素列表
errors	在 span 元素中渲染字段错误

5.2.1 表单标签

表单标签用于渲染 HTML 表单。要使用渲染一个表单输入字段的任何其他标签，必须有一个 form 标签。表单标签的属性见表 5.2。

表 5.2 中的所有标签都是可选的。这个表中没有包含 HTML 属性，如 method 和 action。

commandName 属性或许是其中最重要的属性，因为它定义了模型属性的名称，其中包含了一个表单支持对象（form backing object），其属性将用于填充所生成的表单。如果该属性存在，则必须在返回包含该表单的视图的请求处理方法中添加相应的模型属性。例如，在本章配套的 tags-demo 应用程序中，下列表单标签是在 BookAddForm.jsp 中定义的。

<form:form commandName="book" action="save-book" method="post">
  ...
</form:form>

表 5.2 表单标签的属性

属性	描述
acceptCharset	定义服务器接受的字符编码列表
commandName	暴露表单对象之模型属性的名称，默认为 command
cssClass	定义要应用到被渲染 form 元素的 CSS 类
cssStyle	定义要应用到被渲染 form 元素的 CSS 样式
htmlEscape	接受 true 或者 false，表示被渲染的值是否应该进行 HTML 转义
modelAttribute	暴露表单支持对象的模型属性名称，默认为 command

BookController 类中的 inputBook 方法，是返回 BookAddForm.jsp 的请求处理方法。下面就是 inputBook 方法。

@RequestMapping(value = "/input-book")
public String inputBook(Model model) {
  ...
  model.addAttribute("book", new Book()); return "BookAddForm"; }

此处用 book 属性创建了一个 Book 对象，并添加到 Model。如果没有 Model 属性，BookAddForm.jsp 页面就会抛出异常，因为表单标签无法找到在其 commandName 属性中指定的 form backing object。

此外，一般来说，仍然需要使用 action 和 method 属性。这两个属性都是 HTML 属性，因此不在表 5.2 之中。

5.2.2 input 标签

input 标签渲染<input type="text"/>元素。这个标签最重要的属性是 path，它将这个输入字段绑定到表单支持对象的一个属性。例如，若随附<form/>标签的 commandName 属性值为 book，并且 input 标签的 path 属性值为 isbn，那么，input 标签将被绑定到 Book 对象的 isbn 属性。

表 5.3 展示了 input 标签的属性。表 5.3 中的属性都是可选的，其中不包含 HTML 属性。

表 5.3 input 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的值进行 HTML 转义
path	要绑定的属性路径

举个例子，下面这个 input 标签被绑定到表单支持对象的 isbn 属性。

<form:input id="isbn" path="isbn" cssErrorClass="errorBox"/>

它将会被渲染成下面的<input/>元素：

<input type="text" id="isbn" name="isbn"/>

cssErrorClass 属性不起作用，除非 isbn 属性中有输入验证错误，并且采用同一个表单重新显示用户输入，在这种情况下，input 标签就会被渲染成下面这个 input 元素。

<input type="text" id="isbn" name="isbn" class="errorBox"/>

input 标签也可以绑定到嵌套对象的属性。例如，下列的 input 标签绑定到表单支持对象的 category 属性的 id 属性。

<form:input path="category.id"/>

5.2.3 password 标签

password 标签渲染<input type="password"/>元素，其属性见表 5.4。password 标签与 input 标签相似，只不过它有一个 showPassword 属性。

表 5.4 password 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的值进行 HTML 转义
path	要绑定的属性路径
showPassword	表示应该显示或遮盖密码，默认值为 false

表 5.4 中的所有属性都是可选的，这个表中不包含 HTML 属性。下面是一个 password 标签的例子。

<form:password id="pwd" path="password" cssClass="normal"/>

5.2.4 hidden 标签

hidden 标签渲染<input type="hidden"/>元素，其属性见表 5.5。hidden 标签与 input 标签相似，只不过它没有可视的外观，因此不支持 cssClass 和 cssStyle 属性。

表 5.5 hidden 标签的属性

属性	描述
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的值进行 HTML 转义
path	要绑定的属性路径

表 5.5 中的所有属性都是可选的，其中不包含 HTML 属性。

下面是一个 hidden 标签的例子。

<form:hidden path="productId"/>

5.2.5 textarea 标签

textarea 标签渲染一个 HTML 的 textarea 元素。Textarea 实际上就是支持多行输入的一个 input 元素。textarea 标签的属性见表 5.6。表 5.6 中的所有属性都是可选的，其中不包含 HTML 属性。

表 5.6 textarea 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的值进行 HTML 转义
path	要绑定的属性路径

例如，下面的 textarea 标签就是被绑定到表单支持对象的 note 属性。

<form:textarea path="note" rows="5" cols="80"/>

5.2.6 checkbox 标签

checkbox 标签渲染<input type="checkbox"/>元素。checkbox 标签的属性见表 5.7。表 5.7 中的所有属性都是可选的，其中不包含 HTML 属性。

表 5.7 checkbox 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
label	要作为标签用于被渲染复选框的值
path	要绑定的属性路径

例如，下面的 checkbox 标签绑定到 outOfStock 属性：

<form:checkbox path="outOfStock" value="Out of Stock"/>

5.2.7 radiobutton 标签

radiobutton 标签渲染<input type="radio"/>元素。radiobutton 标签的属性见表 5.8。表 5.8 中的所有属性都是可选的，其中不包含 HTML 属性。

例如，下列的 radiobutton 标签绑定到 newsletter 属性。

Computing Now <form:radiobutton path="newsletter" value="Computing Now"/>
<br/>
Modern Health <form:radiobutton path="newsletter" value="Modern Health"/>

表 5.8 radiobutton 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
label	要作为标签用于被渲染复选框的值
path	要绑定的属性路径

5.2.8 checkboxes 标签

checkboxes 标签渲染多个<input type="checkbox"/>元素。checkboxes 标签的属性见表 5.9。表 5.9 中的属性都是可选的，其中不包含 HTML 属性。

例如，下面的 checkboxes 标签将 model 属性 categoryList 的内容渲染为复选框。checkboxes 标签允许进行多个选择。

<form:checkboxes path="category" items="${categoryList}"/>

表 5.9 checkboxes 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
delimiter	定义两个 input 元素之间的分隔符，默认没有分隔符
element	给每个被渲染的 input 元素都定义一个 HTML 元素，默认为“span”
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
items	用于生成 input 元素的对象的 Collection、Map 或者 Array
itemLabel	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供标签
itemValue	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供值
path	要绑定的属性路径

5.2.9 radiobuttons 标签

radiobuttons 标签渲染多个<input type="radio"/>元素。radiobuttons 标签的属性见表 5.10。

例如，下面的 radiobuttons 标签将 model 属性 categoryList 的内容渲染为单选按钮。每次只能选择一个单选按钮。

<form:radiobuttons path="category" items="${categoryList}"/>

表 5.10 radiobuttons 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
delimiter	定义两个 input 元素之间的分隔符，默认没有分隔符
element	给每一个被渲染的 input 元素都定义一个 HTML 元素，默认为“span”
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
items	用于生成 input 元素的对象的 Collection、Map 或者 Array
itemLabel	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供标签
itemValue	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供值
path	要绑定的属性路径

5.2.10 select 标签

select 标签渲染一个 HTML 的 select 元素。被渲染元素的选项可能来自赋予其 items 属性的一个 Collection、Map、Array，或者来自一个嵌套的 option 或者 options 标签。select 标签的属性见表 5.11。表 5.11 中的所有属性都是可选的，其中不包含 HTML 属性。

items 属性特别有用，因为它可以绑定到对象的 Collection、Map、Array，为 select 元素生成选项。

例如，下面的 select 标签绑定到表单支持对象的 category 属性的 id 属性。它的选项来自 model 属性 categories。每个选项的值均来自 categories collection/map/array 的 id 属性，它的标签来自 name 属性。

<form:select id="category" path="category.id"
  items="${categories}" itemLabel="name"
  itemValue="id"/>

表 5.11 select 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
items	用于生成 input 元素的对象的 Collection、Map 或者 Array
itemLabel	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供标签
itemValue	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供值
path	要绑定的属性路径

5.2.11 option 标签

option 标签渲染 select 元素中使用的一个 HTML 的 option 元素，其属性见表 5.12。表 5.12 中的所有属性都是可选的，其中不包含 HTML 属性。

例如，下面是一个 option 标签的范例。

表 5.12 option 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义

<form:select id="category" path="category.id"
    items="${categories}" itemLabel="name"
    itemValue="id">
  <option value="0">-- Please select --</option>
</form:select>

这个代码片断是渲染一个 select 元素，其选项来自 model 属性 categories，以及 option 标签。

5.2.12 options 标签

options 标签生成一个 HTML 的 option 元素列表，其属性见表 5.13，其中不包含 HTML 属性。

tags-demo 应用程序展示了一个 options 标签的范例。

表 5.13 options 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
cssErrorClass	定义要应用到被渲染 input 元素的 CSS 类，如果 bound 属性中包含错误，则覆盖 cssClass 属性值
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
items	用于生成 input 元素的对象的 Collection、Map 或者 Array
itemLabel	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供标签
itemValue	item 属性中定义的 Collection、Map 或者 Array 中的对象属性，为每个 input 元素提供值

5.2.13 errors 标签

errors 标签渲染一个或者多个 HTML 的 span 元素，每个 span 元素中都包含一个字段错误。这个标签可以用于显示一个特定的字段错误，或者所有字段错误。

errors 标签的属性见表 5.14。表 5.14 中的所有属性都是可选的，其中不包含可能在 HTML 的 span 元素中出现的 HTML 属性。

例如，下面这个 errors 标签显示了所有字段错误。

<form:errors path="*"/>

下面的 errors 标签显示了一个与表单支持对象的 author 属性相关的字段错误。

<form:errors path="author"/>

表 5.14 errors 标签的属性

属性	描述
cssClass	定义要应用到被渲染 input 元素的 CSS 类
cssStyle	定义要应用到被渲染 input 元素的 CSS 样式
Delimiter	分隔多个错误消息的分隔符
element	定义一个包含错误消息的 HTML 元素
htmlEscape	接受 true 或者 false，表示是否应该对被渲染的（多个）值进行 HTML 转义
path	要绑定的错误对象路径