表单辅助函数

表单辅助函数文件包含有助于处理表单的函数。

配置 

自 v4.3.0 起，form_helper 函数中的空 HTML 元素（如 <input>）默认已更改为 HTML5 兼容模式。如果需要与 XHTML 兼容，必须将 app/Config/DocTypes.php 中的 $html5 属性设置为 false。

加载此辅助函数 

使用以下代码加载此辅助函数：

<?php

helper('form');

转义字段值 

可能需要在表单元素中使用 HTML 和引号等字符。为了安全地执行此操作，需要使用通用函数 esc()。

考虑以下示例：

<?php

$string = 'Here is a string containing "quoted" text.';

?>

<input type="text" name="myfield" value="<?= $string ?>">

由于上述字符串包含一组引号，会导致表单损坏。 esc() 函数转换 HTML 特殊字符，使其可以安全使用:

<input type="text" name="myfield" value="<?= esc($string) ?>">

备注

如果使用本页列出的任何表单辅助函数，并以关联数组形式传递值，表单值将自动转义，因此无需调用此函数。仅在创建自己的表单元素（以字符串形式传递）时才需要使用它。

可用函数 

提供以下函数：

form_open([$action = ''[, $attributes = ''[, $hidden = []]]])

参数:

$action (string) -- 表单 action/目标 URI 字符串
$attributes (mixed) -- HTML 属性，作为数组或已转义的字符串
$hidden (array) -- 隐藏字段的定义数组

返回:

HTML 表单起始标签

返回类型:

string

创建一个带有 URL 的表单起始标签，该 URL 基于 Config\App::$baseURL 构建。可以选择添加表单属性和隐藏输入字段，并且会始终根据 app/Config/App.php 配置文件中的 $charset 属性添加 accept-charset 属性。

使用此标签而不是硬编码 HTML 的主要好处是，它允许你的网站在 URL 更改时具有更好的可移植性。

简单示例：

<?php

echo form_open('email/send');

以上示例将创建一个指向你的站点 URL 加上 "email/send" URI 段的表单，如下所示:

<form action="http://example.com/index.php/email/send" method="post" accept-charset="utf-8">

也可以添加 {locale}，如下所示：

<?php

echo form_open('{locale}/email/send');

以上示例将创建一个指向你的站点 URL 加上当前请求语言环境和 "email/send" URI 段的表单，如下所示:

<form action="http://example.com/index.php/en/email/send" method="post" accept-charset="utf-8">

添加属性

可以通过向第二个参数传递关联数组来添加属性，如下所示：
<?php

$attributes = ['class' => 'email', 'id' => 'myform'];
echo form_open('email/send', $attributes);
或者，可以将第二个参数指定为字符串：
<?php

echo form_open('email/send', 'class="email" id="myform"');
以上示例将创建一个类似如下的表单:
<form action="http://example.com/index.php/email/send" class="email" id="myform" method="post" accept-charset="utf-8">
如果启用 CSRF 过滤器，form_open() 将在表单开头生成 CSRF 字段。可以通过将 csrf_id 作为 $attributes 数组的元素来指定此字段的 ID：
<?php

echo form_open('/u/sign-up', ['csrf_id' => 'my-id']);
将返回:
<form action="http://example.com/index.php/u/sign-up" method="post" accept-charset="utf-8">
<input type="hidden" id="my-id" name="csrf_test_name" value="964ede6e0ae8a680f7b8eab69136717d">
备注

要使用 CSRF 字段的自动生成功能，需要在 app/Config/Filters.php 文件中启用 CSRF 过滤器。在大多数情况下，表单页面使用 GET 方法请求。通常，POST/PUT/DELETE/PATCH 请求需要 CSRF 保护，但即使对于 GET 请求，显示表单的页面也必须启用 CSRF 过滤器。

如果通过 $globals 启用 CSRF 过滤器，它将对所有请求类型有效。但如果使用 public array $methods = ['POST' => ['csrf']]; 启用 CSRF 过滤器，则不会在 GET 请求中添加隐藏的 CSRF 字段。

添加隐藏输入字段

可以通过向第三个参数传递关联数组来添加隐藏字段，如下所示：
<?php

$hidden = ['username' => 'Joe', 'member_id' => '234'];
echo form_open('email/send', '', $hidden);
可以通过向第二个参数传递任何 false 值来跳过它。

以上示例将创建一个类似如下的表单:
<form action="http://example.com/index.php/email/send" method="post" accept-charset="utf-8">
    <input type="hidden" name="username" value="Joe">
    <input type="hidden" name="member_id" value="234">

form_open_multipart([$action = ''[, $attributes = ''[, $hidden = []]]])

参数:

$action (string) -- 表单 action/目标 URI 字符串
$attributes (mixed) -- HTML 属性，作为数组或已转义的字符串
$hidden (array) -- 隐藏字段的定义数组

返回:

HTML multipart 表单起始标签

返回类型:

string

此函数与上面的 form_open() 完全相同，只是它添加了 multipart 属性，如果你想使用表单上传文件，这是必需的。

form_hidden($name[, $value = ''])

参数:

$name (string) -- 字段名称
$value (string) -- 字段值

返回:

HTML 隐藏输入元素

返回类型:

string

生成隐藏输入字段。可以提交名称/值字符串来创建一个字段：

<?php

form_hidden('username', 'johndoe');
// Would produce: <input type="hidden" name="username" value="johndoe">

... 或者可以提交关联数组来创建多个字段：

<?php

$data = [
    '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">
 */

也可以向值字段传递关联数组：

<?php

$data = [
    '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">
 */

如果要创建带有额外属性的隐藏输入字段：

<?php

$data = [
    '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 = ''[, $type = 'text']]]])

参数:

$data (array) -- 字段属性数据
$value (string) -- 字段值
$extra (mixed) -- 要添加到标签的额外属性，作为数组或字面字符串
$type (string) -- 输入字段的类型。例如，'text'、'email'、'number' 等

返回:

HTML 文本输入元素

返回类型:

string

生成标准文本输入字段。可以最少在第一个和第二个参数中传递字段名称和值：

<?php

echo form_input('username', 'johndoe');
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe">
 */

或者可以传递包含希望表单包含的任何数据的关联数组：

<?php

$data = [
    '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%">
 */

如果需要布尔属性，传递布尔值（true/false）。在这种情况下，布尔值无关紧要：

<?php

$data = [
    'name'     => 'username',
    'id'       => 'username',
    'value'    => '',
    'required' => true,
];
echo form_input($data);
/*
 * Would produce:
 * <input type="text" name="username" value="" id="username" required>
 */

如果希望表单包含一些额外数据，如 JavaScript，可以在第三个参数中将其作为字符串传递：

<?php

$js = 'onClick="some_function ()"';
echo form_input('username', 'johndoe', $js);
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe" onClick="some_function ()">
 */

或者可以将其作为数组传递：

<?php

$js = ['onClick' => 'some_function ();'];
echo form_input('username', 'johndoe', $js);
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe" onClick="some_function ();">
 */

为了支持扩展范围的 HTML5 输入字段，可以在第四个参数中传递输入类型：

<?php

echo form_input('email', 'joe@example.com', ['placeholder' => 'Email Address...'], 'email');
/*
 * Would produce:
 * <input type="email" name="email" value="joe@example.com" placeholder="Email Address...">
 */

form_password([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (array) -- 字段属性数据
$value (string) -- 字段值
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML 密码输入元素

返回类型:

string

此函数在所有方面都与上面的 form_input() 函数相同，只是它使用 "password" 输入类型。

form_upload([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (array) -- 字段属性数据
$value (string) -- 字段值
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML 文件上传输入元素

返回类型:

string

此函数在所有方面都与上面的 form_input() 函数相同，只是它使用 "file" 输入类型，允许它用于上传文件。

form_textarea([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (array) -- 字段属性数据
$value (string) -- 字段值
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML textarea 元素

返回类型:

string

此函数在所有方面都与上面的 form_input() 函数相同，只是它生成 "textarea" 类型。

备注

在上面的示例中，需要指定 rows 和 cols 属性，而不是 maxlength 和 size 属性。

form_dropdown([$name = ''[, $options = [][, $selected = [][, $extra = '']]]])

参数:

$name (string) -- 字段名称
$options (array) -- 要列出的选项的关联数组
$selected (array) -- 用 selected 属性标记的字段列表
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML select（下拉框）元素

返回类型:

string

创建标准下拉框字段。第一个参数将包含字段名称，第二个参数将包含选项的关联数组，第三个参数将包含希望选择的值。也可以通过第三个参数传递多个项目的数组，辅助函数将为你创建多选。

示例：

<?php

$options = [
    'small'  => 'Small Shirt',
    'med'    => 'Medium Shirt',
    'large'  => 'Large Shirt',
    'xlarge' => 'Extra Large Shirt',
];

$shirts_on_sale = ['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>
 */

如果希望起始 <select> 标签包含额外数据，如 id 属性或 JavaScript，可以在第四个参数中将其作为字符串传递：

<?php

$js = 'id="shirts" onChange="some_function();"';
echo form_dropdown('shirts', $options, 'large', $js);

或者可以将其作为数组传递：

<?php

$js = [
    'id'       => 'shirts',
    'onChange' => 'some_function();',
];
echo form_dropdown('shirts', $options, 'large', $js);

如果作为 $options 传递的数组是多维数组，那么 form_dropdown() 将生成一个 <optgroup>，以数组键作为标签。

form_multiselect([$name = ''[, $options = [][, $selected = [][, $extra = '']]]])

参数:

$name (string) -- 字段名称
$options (array) -- 要列出的选项的关联数组
$selected (array) -- 用 selected 属性标记的字段列表
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

带有 multiple 属性的 HTML select 元素

返回类型:

string

创建标准多选字段。第一个参数将包含字段名称，第二个参数将包含选项的关联数组，第三个参数将包含希望选择的值。

参数使用与上面的 form_dropdown() 相同，当然，字段名称需要使用 POST 数组语法，例如 foo[]。

form_fieldset([$legend_text = ''[, $attributes = []]])

参数:

$legend_text (string) -- 要放在 <legend> 标签中的文本
$attributes (array) -- 要设置在 <fieldset> 标签上的属性

返回:

HTML fieldset 开始标签

返回类型:

string

生成 fieldset/legend 字段。

示例：

<?php

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>

与其他函数类似，如果希望设置额外属性，可以在第二个参数中提交关联数组：

<?php

$attributes = [
    '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) -- 在闭合标签之后追加的任何内容（按原样输出）

返回:

HTML fieldset 闭合标签

返回类型:

string

生成闭合 </fieldset> 标签。使用此函数的唯一好处是，它可以传递数据，这些数据将被添加到标签下方。例如

<?php

$string = '</div></div>';
echo form_fieldset_close($string);
// Would produce: </fieldset></div></div>

form_checkbox([$data = ''[, $value = ''[, $checked = false[, $extra = '']]]])

参数:

$data (array) -- 字段属性数据
$value (string) -- 字段值
$checked (bool) -- 是否将复选框标记为 checked
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML 复选框输入元素

返回类型:

string

生成复选框字段。简单示例：

<?php

echo form_checkbox('newsletter', 'accept', true);
// Would produce:  <input type="checkbox" name="newsletter" value="accept" checked="checked">

第三个参数包含布尔值 true/false，以确定是否应该选中复选框。

与此辅助函数中的其他表单函数类似，也可以向函数传递属性数组：

<?php

$data = [
    '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 等额外数据，可以在第四个参数中将其作为字符串传递：

<?php

$js = 'onClick="some_function()"';
echo form_checkbox('newsletter', 'accept', true, $js);

或者可以将其作为数组传递：

<?php

$js = ['onClick' => 'some_function();'];
echo form_checkbox('newsletter', 'accept', true, $js);

form_radio([$data = ''[, $value = ''[, $checked = false[, $extra = '']]]])

参数:

$data (array) -- 字段属性数据
$value (string) -- 字段值
$checked (bool) -- 是否将单选按钮标记为 checked
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML 单选输入元素

返回类型:

string

此函数在所有方面都与上面的 form_checkbox() 函数相同，只是它使用 "radio" 输入类型。

form_label([$label_text = ''[, $id = ''[, $attributes = []]]])

参数:

$label_text (string) -- 要放在 <label> 标签中的文本
$id (string) -- 正在为其创建标签的表单元素的 ID
$attributes (string) -- HTML 属性

返回:

HTML label 元素

返回类型:

string

生成 <label>。简单示例：

<?php

echo form_label('What is your Name', 'username');
// Would produce:  <label for="username">What is your Name</label>

与其他函数类似，如果希望设置额外属性，可以在第三个参数中提交关联数组。

示例：

<?php

$attributes = [
    '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) -- 按钮名称
$value (string) -- 按钮值
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML input submit 元素

返回类型:

string

生成标准提交按钮。简单示例：

<?php

echo form_submit('mysubmit', 'Submit Post!');
// Would produce:  <input type="submit" name="mysubmit" value="Submit Post!">

与其他函数类似，如果希望设置自己的属性，可以在第一个参数中提交关联数组。第三个参数允许向表单添加额外数据，如 JavaScript。

form_reset([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (string) -- 按钮名称
$value (string) -- 按钮值
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML input reset 元素

返回类型:

string

生成标准重置按钮。使用方式与 form_submit() 相同。

form_button([$data = ''[, $content = ''[, $extra = '']]])

参数:

$data (string) -- 按钮名称
$content (string) -- 按钮标签
$extra (mixed) -- 要添加到标签的额外属性（可以是一个数组或一个字符串）

返回:

HTML button 元素

返回类型:

string

生成标准按钮元素。可以最少在第一个和第二个参数中传递按钮名称和内容：

<?php

echo form_button('name', 'content');
// Would produce: <button name="name" type="button">Content</button>

或者，你可以传入一个关联数组，其中包含你希望表单中包含的任何数据：

<?php

$data = [
    '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，可以在第三个参数中将其作为字符串传递：

<?php

$js = 'onClick="some_function()"';
echo form_button('mybutton', 'Click Me', $js);

form_close([$extra = ''])

参数:

$extra (string) -- 在闭合标签之后追加的任何内容（按原样输出）

返回:

HTML 表单闭合标签

返回类型:

string

生成闭合 </form> 标签。使用此函数的唯一好处是，它可以传递数据，这些数据将被添加到标签下方。例如：

<?php

$string = '</div></div>';
echo form_close($string);
// Would produce:  </form> </div></div>

set_value($field[, $default = ''[, $html_escape = true]])

参数:

$field (string) -- 字段名称
$default (string) -- 默认值
$html_escape (bool) -- 是否对该值禁用 HTML 转义

返回:

字段值

返回类型:

string

允许设置 input 或 textarea 元素的值。必须通过函数的第一个参数提供字段名称。第二个（可选）参数允许为字段值设置默认值。第三个（可选）参数允许禁用 HTML 转义，以防你需要将此函数与 form_input() 等函数结合使用，从而避免双重转义。

示例:

<input type="text" name="quantity" value="<?= set_value('quantity', '0') ?>" size="50">

以上表单在首次加载时将显示 "0"。

set_select($field[, $value = ''[, $default = false]])

参数:

$field (string) -- 字段名称
$value (string) -- 要检查的值
$default (string) -- 该值是否也是默认值

返回:

'selected' 属性或空字符串

返回类型:

string

如果使用 <select> 菜单，此函数允许显示已选择的菜单项。

第一个参数必须包含选择菜单的名称，第二个参数必须包含每个项目的值，第三个（可选）参数允许将项目设置为默认值（使用布尔值 true/false）。

示例:

<select name="myselect">
    <option value="one" <?= set_select('myselect', 'one', true) ?>>One</option>
    <option value="two" <?= set_select('myselect', 'two') ?>>Two</option>
    <option value="three" <?= set_select('myselect', 'three') ?>>Three</option>
</select>

set_checkbox($field[, $value = ''[, $default = false]])

参数:

$field (string) -- 字段名称
$value (string) -- 要检查的值
$default (string) -- 该值是否也是默认值

返回:

'checked' 属性或空字符串

返回类型:

string

允许显示复选框在提交时的状态。

第一个参数必须包含复选框的名称，第二个参数必须包含其值，第三个（可选）参数允许将项目设置为默认值（使用布尔值 true/false）。

示例:

<input type="checkbox" name="mycheck[]" value="1" <?= set_checkbox('mycheck', '1') ?>>
<input type="checkbox" name="mycheck[]" value="2" <?= set_checkbox('mycheck', '2') ?>>

set_radio($field[, $value = ''[, $default = false]])

参数:

$field (string) -- 字段名称
$value (string) -- 要检查的值
$default (string) -- 该值是否也是默认值

返回:

'checked' 属性或空字符串

返回类型:

string

允许显示单选按钮在提交时的状态。此函数与上面的 set_checkbox() 函数相同。

示例:

<input type="radio" name="myradio" value="1" <?= set_radio('myradio', '1', true) ?>>
<input type="radio" name="myradio" value="2" <?= set_radio('myradio', '2') ?>>

validation_errors()

Added in version 4.3.0.

返回:: 验证错误
返回类型:: array

返回验证错误。首先，此函数检查存储在 Session 中的验证错误。要将错误存储在 Session 中，需要将 withInput() 与 redirect() 一起使用。

返回的数组与 Validation::getErrors() 相同。详细信息请参见验证。

备注

此函数不适用于模型内验证。如果要获取模型验证中的验证错误，请参见获取验证错误。

示例:

<?php $errors = validation_errors(); ?>

validation_list_errors($template = 'list')

Added in version 4.3.0.

参数:

$template (string) -- 验证模板名称

返回:

验证错误的渲染 HTML

返回类型:

string

返回验证错误渲染后的 HTML。

参数 $template 是验证模板名称。详细信息请参见自定义错误显示。

此函数内部使用 validation_errors()。

备注

此函数不适用于模型内验证。如果要获取模型验证中的验证错误，请参见获取验证错误。

示例:

<?= validation_list_errors() ?>

validation_show_error($field, $template = 'single')

Added in version 4.3.0.

参数:

$field (string) -- 字段名称
$template (string) -- 验证模板名称

返回:

验证错误渲染后的 HTML

返回类型:

string

以格式化的 HTML 形式返回指定字段的单个错误。

参数 $template 是验证模板名称。详细信息请参见自定义错误显示。

此函数内部使用 validation_errors()。

备注

此函数不适用于模型内验证。如果要获取模型验证中的验证错误，请参见获取验证错误。

示例:

<?= validation_show_error('username') ?>

表单辅助函数

配置

加载此辅助函数

转义字段值

可用函数

配置 

加载此辅助函数 

转义字段值 

可用函数 