表单辅助函数
最后更新于：2022-04-01 03:56:10
# 表单辅助函数
表单辅助函数包含了一些函数用于帮助你处理表单。
[TOC=2,3]
## [加载辅助函数](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#id5)
使用下面的代码来加载表单辅助函数:
~~~
$this->load->helper('form');
~~~
## [对域值转义](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#id6)
你可能会需要在表单元素中使用 HTML 或者诸如引号这样的字符，为了安全性， 你需要使用 [通用函数](http://codeigniter.org.cn/user_guide/general/common_functions.html) html_escape() 。
考虑下面这个例子:
~~~
$string = 'Here is a string containing "quoted" text.';
<input type="text" name="myfield" value="<?php echo $string; ?>" />
~~~
因为上面的字符串中包含了一对引号，它会破坏表单，使用 [html_escape()](http://codeigniter.org.cn/user_guide/general/common_functions.html#html_escape "html_escape") 函数可以对 HTML 的特殊字符进行转义，从而可以安全的在域值中使用字符串:
~~~
<input type="text" name="myfield" value="<?php echo html_escape($string); ?>" />
~~~
注解
如果你使用了这个页面上介绍的任何一个函数，表单的域值会被自动转义， 所以你无需再调用这个函数。只有在你创建自己的表单元素时需要使用它。
## [可用函数](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#id7)
该辅助函数有下列可用函数：
form_open([$action = ''[, $attributes = ''[, $hidden = array()]]])
参数:
* **$action** (string) -- Form action/target URI string
* **$attributes** (array) -- HTML attributes
* **$hidden** (array) -- An array of hidden fields' definitions
返回: An HTML form opening tag
返回类型: string
生成一个 form 起始标签，并且它的 action URL 会根据你的配置文件自动生成。 你还可以给表单添加属性和隐藏域，另外，它还会根据你配置文件中的字符集参数 自动生成 accept-charset 属性。
使用该函数来生成标签比你自己写 HTML 代码最大的好处是：当你的 URL 变动时， 它可以提供更好的可移植性。
这里是个简单的例子:
~~~
echo form_open('email/send');
~~~
上面的代码会创建一个表单，它的 action 为根 URL 加上 "email/send"，向下面这样:
~~~
<form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send">
~~~
**添加属性**
>
>
> 可以通过第二个参数传递一个关联数组来添加属性，例如:
>
>
>
>
>
> ~~~
> $attributes = array('class' => 'email', 'id' => 'myform');
> echo form_open('email/send', $attributes);
> ~~~
>
>
>
>
>
> 另外，第二个参数你也可以直接使用字符串:
>
>
>
>
>
> ~~~
> echo form_open('email/send', 'class="email" id="myform"');
> ~~~
>
>
>
>
>
> 上面的代码会创建一个类似于下面的表单:
>
>
>
>
>
> ~~~
> <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform">
> ~~~
>
>
>
>
>
>
**添加隐藏域**
>
>
> 可以通过第三个参数传递一个关联数组来添加隐藏域，例如:
>
>
>
>
>
> ~~~
> $hidden = array('username' => 'Joe', 'member_id' => '234');
> echo form_open('email/send', '', $hidden);
> ~~~
>
>
>
>
>
> 你可以使用一个空值跳过第二个参数。
>
> 上面的代码会创建一个类似于下面的表单:
>
>
>
>
>
> ~~~
> <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send">
> <input type="hidden" name="username" value="Joe" />
> <input type="hidden" name="member_id" value="234" />
> ~~~
>
>
>
>
>
>
form_open_multipart([$action = ''[, $attributes = array()[, $hidden = array()]])
参数:
* **$action** (string) -- Form action/target URI string
* **$attributes** (array) -- HTML attributes
* **$hidden** (array) -- An array of hidden fields' definitions
返回: An HTML multipart form opening tag
返回类型: string
这个函数和上面的 [form_open()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_open "form_open") 函数完全一样， 只是它会给表单添加一个 multipart 属性，在你使用表单上传文件时必须使用它。
form_hidden($name[, $value = ''])
参数:
* **$name** (string) -- Field name
* **$value** (string) -- Field value
返回: An HTML hidden input field tag
返回类型: string
生成隐藏域。你可以使用名称和值两个参数来创建一个隐藏域:
~~~
form_hidden('username', 'johndoe');
// Would produce: <input type="hidden" name="username" value="johndoe" />
~~~
... 或者你可以使用一个关联数组，来生成多个隐藏域:
~~~
$data = array(
'name' => 'John Doe',
'email' => 'john@example.com',
'url' => 'http://example.com'
);
echo form_hidden($data);
/*
Would produce:
<input type="hidden" name="name" value="John Doe" />
<input type="hidden" name="email" value="john@example.com" />
<input type="hidden" name="url" value="http://example.com" />
*/
~~~
你还可以向第二个参数传递一个关联数组:
~~~
$data = array(
'name' => 'John Doe',
'email' => 'john@example.com',
'url' => 'http://example.com'
);
echo form_hidden('my_array', $data);
/*
Would produce:
<input type="hidden" name="my_array[name]" value="John Doe" />
<input type="hidden" name="my_array[email]" value="john@example.com" />
<input type="hidden" name="my_array[url]" value="http://example.com" />
*/
~~~
如果你想创建带有其他属性的隐藏域，可以这样:
~~~
$data = array(
'type' => 'hidden',
'name' => 'email',
'id' => 'hiddenemail',
'value' => 'john@example.com',
'class' => 'hiddenemail'
);
echo form_input($data);
/*
Would produce:
<input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" />
*/
~~~
form_input([$data = ''[, $value = ''[, $extra = '']])
参数:
* **$data** (array) -- Field attributes data
* **$value** (string) -- Field value
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML text input field tag
返回类型: string
用于生成标准的文本输入框，你可以简单的使用文本域的名称和值:
~~~
echo form_input('username', 'johndoe');
~~~
或者使用一个关联数组，来包含任何你想要的数据:
~~~
$data = array(
'name' => 'username',
'id' => 'username',
'value' => 'johndoe',
'maxlength' => '100',
'size' => '50',
'style' => 'width:50%'
);
echo form_input($data);
/*
Would produce:
<input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" />
*/
~~~
如果你还希望能包含一些额外的数据，譬如 JavaScript ，你可以通过第三个参数传一个字符串:
~~~
$js = 'onClick="some_function()"';
echo form_input('username', 'johndoe', $js);
~~~
form_password([$data = ''[, $value = ''[, $extra = '']]])
参数:
* **$data** (array) -- Field attributes data
* **$value** (string) -- Field value
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML password input field tag
返回类型: string
该函数和上面的 form_input() 函数一样，只是生成的输入框为 "password" 类型。
form_upload([$data = ''[, $value = ''[, $extra = '']]])
参数:
* **$data** (array) -- Field attributes data
* **$value** (string) -- Field value
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML file upload input field tag
返回类型: string
该函数和上面的 form_input() 函数一样，只是生成的输入框为 "file" 类型， 可以用来上传文件。
form_textarea([$data = ''[, $value = ''[, $extra = '']]])
参数:
* **$data** (array) -- Field attributes data
* **$value** (string) -- Field value
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML textarea tag
返回类型: string
该函数和上面的 form_input() 函数一样，只是生成的输入框为 "textarea" 类型。
注解
对于 textarea 类型的输入框，你可以使用 rows 和 cols 属性， 来代替上面例子中的 maxlength 和 size 属性。
form_dropdown([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]])
参数:
* **$name** (string) -- Field name
* **$options** (array) -- An associative array of options to be listed
* **$selected** (array) -- List of fields to mark with the selected attribute
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML dropdown select field tag
返回类型: string
用于生成一个标准的下拉框域。第一个参数为域的名称，第二个参数为一个关联数组， 包含所有的选项，第三个参数为你希望默认选中的值。你也可以把第三个参数设置成 一个包含多个值的数组，CodeIgniter 将会为你生成多选下拉框。
例如:
~~~
$options = array(
'small' => 'Small Shirt',
'med' => 'Medium Shirt',
'large' => 'Large Shirt',
'xlarge' => 'Extra Large Shirt',
);
$shirts_on_sale = array('small', 'large');
echo form_dropdown('shirts', $options, 'large');
/*
Would produce:
<select name="shirts">
<option value="small">Small Shirt</option>
<option value="med">Medium Shirt</option>
<option value="large" selected="selected">Large Shirt</option>
<option value="xlarge">Extra Large Shirt</option>
</select>
*/
echo form_dropdown('shirts', $options, $shirts_on_sale);
/*
Would produce:
<select name="shirts" multiple="multiple">
<option value="small" selected="selected">Small Shirt</option>
<option value="med">Medium Shirt</option>
<option value="large" selected="selected">Large Shirt</option>
<option value="xlarge">Extra Large Shirt</option>
</select>
*/
~~~
如果你希望为起始标签 添加一些额外的数据，例如 id 属性或 JavaScript ， 你可以通过第四个参数传一个字符串:
~~~
$js = 'id="shirts" onChange="some_function();"';
echo form_dropdown('shirts', $options, 'large', $js);
~~~
如果你传递的 $options 数组是个多维数组，form_dropdown() 函数将会生成带 的下拉框，并使用数组的键作为 label 。
form_multiselect([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]])
参数:
* **$name** (string) -- Field name
* **$options** (array) -- An associative array of options to be listed
* **$selected** (array) -- List of fields to mark with the selected attribute
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML dropdown multiselect field tag
返回类型: string
用于生成一个标准的多选下拉框。第一个参数为域的名称，第二个参数为一个关联数组， 包含所有的选项，第三个参数为你希望默认选中的一个或多个值。
参数的用法和上面的 [form_dropdown()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_dropdown "form_dropdown") 函数一样，只是域的名称需要使用 数组语法，例如：foo[]
form_fieldset([$legend_text = ''[, $attributes = array()]])
参数:
* **$legend_text** (string) -- Text to put in the tag
* **$attributes** (array) -- Attributes to be set on the tag
返回:
An HTML fieldset opening tag
返回类型: string
用于生成 fieldset 和 legend 域。
例如:
~~~
echo form_fieldset('Address Information');
echo "<p>fieldset content here</p>\n";
echo form_fieldset_close();
/*
Produces:
<fieldset>
<legend>Address Information</legend>
<p>form content here</p>
</fieldset>
*/
~~~
和其他的函数类似，你也可以通过给第二个参数传一个关联数组来添加额外的属性:
~~~
$attributes = array(
'id' => 'address_info',
'class' => 'address_info'
);
echo form_fieldset('Address Information', $attributes);
echo "<p>fieldset content here</p>\n";
echo form_fieldset_close();
/*
Produces:
<fieldset id="address_info" class="address_info">
<legend>Address Information</legend>
<p>form content here</p>
</fieldset>
*/
~~~
form_fieldset_close([$extra = ''])
参数:
* **$extra** (string) -- Anything to append after the closing tag, as is
返回: An HTML fieldset closing tag
返回类型: string
用于生成结束标签 ，使用这个函数唯一的一个好处是， 它可以在结束标签的后面加上一些其他的数据。例如：
~~~
$string = '</div></div>';
echo form_fieldset_close($string);
// Would produce: </fieldset></div></div>
~~~
form_checkbox([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]])
参数:
* **$data** (array) -- Field attributes data
* **$value** (string) -- Field value
* **$checked** (bool) -- Whether to mark the checkbox as being checked
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML checkbox input tag
返回类型: string
用于生成一个复选框，例如:
~~~
echo form_checkbox('newsletter', 'accept', TRUE);
// Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" />
~~~
第三个参数为布尔值 TRUE 或 FALSE ，用于指定复选框默认是否为选定状态。
和其他函数一样，你可以传一个属性的数组给它:
~~~
$data = array(
'name' => 'newsletter',
'id' => 'newsletter',
'value' => 'accept',
'checked' => TRUE,
'style' => 'margin:10px'
);
echo form_checkbox($data);
// Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" />
~~~
另外，如果你希望向标签中添加额外的数据如 JavaScript ，也可以传一个字符串给第四个参数:
~~~
$js = 'onClick="some_function()"';
echo form_checkbox('newsletter', 'accept', TRUE, $js)
~~~
form_radio([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]])
参数:
* **$data** (array) -- Field attributes data
* **$value** (string) -- Field value
* **$checked** (bool) -- Whether to mark the radio button as being checked
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML radio input tag
返回类型: string
该函数和 [form_checkbox()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_checkbox "form_checkbox") 函数完全一样，只是它生成的是单选框。
form_label([$label_text = ''[, $id = ''[, $attributes = array()]]])
参数:
* **$label_text** (string) -- Text to put in the tag
* **$id** (string) -- ID of the form element that we're making a label for
* **$attributes** (string) -- HTML attributes
返回: An HTML field label tag
返回类型: string
生成 标签，例如:
~~~
echo form_label('What is your Name', 'username');
// Would produce: <label for="username">What is your Name</label>
~~~
和其他的函数一样，如果你想添加额外的属性的话，可以传一个关联数组给第三个参数。
例如:
~~~
$attributes = array(
'class' => 'mycustomclass',
'style' => 'color: #000;'
);
echo form_label('What is your Name', 'username', $attributes);
// Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label>
~~~
form_submit([$data = ''[, $value = ''[, $extra = '']]])
参数:
* **$data** (string) -- Button name
* **$value** (string) -- Button value
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML input submit tag
返回类型: string
用于生成一个标准的提交按钮。例如:
~~~
echo form_submit('mysubmit', 'Submit Post!');
// Would produce: <input type="submit" name="mysubmit" value="Submit Post!" />
~~~
和其他的函数一样，如果你想添加额外的属性的话，可以传一个关联数组给第一个参数， 第三个参数可以向表单添加额外的数据，例如 JavaScript 。
form_reset([$data = ''[, $value = ''[, $extra = '']]])
参数:
* **$data** (string) -- Button name
* **$value** (string) -- Button value
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML input reset button tag
返回类型: string
用于生成一个标准的重置按钮。用法和 form_submit() 函数一样。
form_button([$data = ''[, $content = ''[, $extra = '']]])
参数:
* **$data** (string) -- Button name
* **$content** (string) -- Button label
* **$extra** (string) -- Extra attributes to be added to the tag as is
返回: An HTML button tag
返回类型: string
用于生成一个标准的按钮，你可以简单的使用名称和内容来生成按钮:
~~~
echo form_button('name','content');
// Would produce: <button name="name" type="button">Content</button>
~~~
或者使用一个关联数组，来包含任何你想要的数据:
~~~
$data = array(
'name' => 'button',
'id' => 'button',
'value' => 'true',
'type' => 'reset',
'content' => 'Reset'
);
echo form_button($data);
// Would produce: <button name="button" id="button" value="true" type="reset">Reset</button>
~~~
如果你还希望能包含一些额外的数据，譬如 JavaScript ，你可以通过第三个参数传一个字符串:
~~~
$js = 'onClick="some_function()"';
echo form_button('mybutton', 'Click Me', $js);
~~~
form_close([$extra = ''])
参数:
* **$extra** (string) -- Anything to append after the closing tag, as is
返回: An HTML form closing tag
返回类型:string
用于生成结束标签 ，使用这个函数唯一的一个好处是， 它可以在结束标签的后面加上一些其他的数据。例如：
> $string = ''; echo form_close($string); // Would produce:
set_value($field[, $default = ''[, $html_escape = TRUE]])
参数:
* **$field** (string) -- Field name
* **$default** (string) -- Default value
* **$html_escape** (bool) -- Whether to turn off HTML escaping of the value
返回: Field value
返回类型: string
用于你显示 input 或者 textarea 类型的输入框的值。你必须在第一个参数中指定名称， 第二个参数是可选的，允许你设置一个默认值，第三个参数也是可选，可以禁用对值的转义， 当你在和 form_input() 函数一起使用时，可以避免重复转义。
例如:
~~~
<input type="text" name="quantity" value="<?php echo set_value('quantity', '0'); ?>" size="50" />
~~~
当上面的表单元素第一次加载时将会显示 "0" 。
set_select($field[, $value = ''[, $default = FALSE]])
参数:
* **$field** (string) -- Field name
* **$value** (string) -- Value to check for
* **$default** (string) -- Whether the value is also a default one
返回: 'selected' attribute or an empty string
返回类型: string
如果你使用 下拉菜单，此函数允许你显示选中的菜单项。
第一个参数为下拉菜单的名称，第二个参数必须包含每个菜单项的值。 第三个参数是可选的，用于设置菜单项是否为默认选中状态（TRUE / FALSE）。
例如:
~~~
<select name="myselect">
<option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option>
<option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option>
<option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option>
</select>
~~~
set_checkbox($field[, $value = ''[, $default = FALSE]])
参数:
* **$field** (string) -- Field name
* **$value** (string) -- Value to check for
* **$default** (string) -- Whether the value is also a default one
返回: 'checked' attribute or an empty string
返回类型: string
允许你显示一个处于提交状态的复选框。
第一个参数必须包含此复选框的名称，第二个参数必须包含它的值， 第三个参数是可选的，用于设置复选框是否为默认选中状态（TRUE / FALSE）。
例如:
~~~
<input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> />
<input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> />
~~~
set_radio($field[, $value = ''[, $default = FALSE]])
参数:
* **$field** (string) -- Field name
* **$value** (string) -- Value to check for
* **$default** (string) -- Whether the value is also a default one
返回: 'checked' attribute or an empty string
返回类型: string
允许你显示那些处于提交状态的单选框。 该函数和上面的 [set_checkbox()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#set_checkbox "set_checkbox") 函数一样。
例如:
~~~
<input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> />
<input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> />
~~~
注解
如果你正在使用表单验证类，你必须为你的每一个表单域指定一个规则， 即使是空的，这样可以确保 set_*() 函数能正常运行。 这是因为如果定义了一个表单验证对象，set_*() 函数的控制权将移交到表单验证类， 而不是辅助函数函数。
form_error([$field = ''[, $prefix = ''[, $suffix = '']]])
参数:
* **$field** (string) -- Field name
* **$prefix** (string) -- Error opening tag
* **$suffix** (string) -- Error closing tag
返回: HTML-formatted form validation error message(s)
返回类型: string
从 [表单验证类](http://codeigniter.org.cn/user_guide/libraries/form_validation.html) 返回验证错误消息， 并附上验证出错的域的名称，你可以设置错误消息的起始和结束标签。
例如:
~~~
// Assuming that the 'username' field value was incorrect:
echo form_error('myfield', '<div class="error">', '</div>');
// Would produce: <div class="error">Error message associated with the "username" field.</div>
~~~
validation_errors([$prefix = ''[, $suffix = '']])
参数:
* **$prefix** (string) -- Error opening tag
* **$suffix** (string) -- Error closing tag
返回: HTML-formatted form validation error message(s)
返回类型: string
和 [form_error()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_error "form_error") 函数类似，返回所有 [表单验证类](http://codeigniter.org.cn/user_guide/libraries/form_validation.html) 生成的错误信息，你可以为为每个错误消息设置起始和结束标签。
例如:
~~~
echo validation_errors('<span class="error">', '</span>');
/*
Would produce, e.g.:
<span class="error">The "email" field doesn't contain a valid e-mail address!</span>
<span class="error">The "password" field doesn't match the "repeat_password" field!</span>
*/
~~~
form_prep($str)
参数:
* **$str** (string) -- Value to escape
返回: Escaped value
返回类型: string
允许你在表单元素中安全的使用 HTML 和譬如引号这样的字符，而不用担心对表单造成破坏。
注解
如果你使用了这个页面上介绍的任何一个函数，表单的域值会被自动转义， 所以你无需再调用这个函数。只有在你创建自己的表单元素时需要使用它。
注解
该函数已经废弃，现在只是 [通用函数](http://codeigniter.org.cn/user_guide/general/common_functions.html) html_escape() 的一个别名，请使用 html_escape() 代替它。