创建表单

在 Yii 中使用表单的主要方式是通过 yii\widgets\ActiveForm。如果是基于模型的表单应首选这种方式。此外，在 yii\helpers\Html中也有一些实用的方法用于添加按钮和帮助文本。

在客户端上显示的表单，大多数情况下有一个相应的模型，用来验证其输入的服务器数据 (可在输入验证一节获取关于验证的细节)。当创建基于模型的表单时，第一步是定义模型本身。该模式可以是一个基于活动记录的类，表示数据库中的数据，也可以是一个基于通用模型的类（继承自 yii\base\Model ），来获取任意的输入数据，如登录表单。在下面的例子中，我们展示了一个用来做登录表单的通用模型：

<?php

class LoginForm extends \yii\base\Model
{
    public $username;
    public $password;

    public function rules()
    {
        return [
            // 在这里定义验证规则
        ];
    }
}

在控制器中，我们将传递一个模型的实例到视图，其中 yii\widgets\ActiveForm 小部件用来显示表单：

<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;

$form = ActiveForm::begin([
    'id' => 'login-form',
    'options' => ['class' => 'form-horizontal'],
]) ?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>

    <div class="form-group">
        <div class="col-lg-offset-1 col-lg-11">
            <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
        </div>
    </div>
<?php ActiveForm::end() ?>

在上面的代码中，yii\widgets\ActiveForm::begin() 不仅创建了一个表单实例，同时也标志着表单的开始。放在 yii\widgets\ActiveForm::begin() 与 yii\widgets\ActiveForm::end() 之间的所有内容都被包裹在 HTML 的 <form> 标签中。与任何小部件一样，你可以指定一些选项，通过传递数组到 begin 方法中来配置该小部件。在这种情况下，一个额外的 CSS 类和 ID 会在 <form> 标签中使用。要查看所有可用的选项，请参阅 API 文档的 yii\widgets\ActiveForm。

为了在表单中创建表单元素与元素的标签，以及任何适用的 JavaScript 验证，yii\widgets\ActiveForm::field() 方法在调用时，会返回一个 yii\widgets\ActiveField 的实例。直接输出该方法时，结果是一个普通的（文本）输入。要自定义输出，可以附加上 yii\widgets\ActiveField 的其它方法来一起调用：

// 一个密码输入框
<?= $form->field($model, 'password')->passwordInput() ?>
// 增加一个提示标签
<?= $form->field($model, 'username')->textInput()->hint('Please enter your name')->label('Name') ?>
// 创建一个 HTML5 邮箱输入框
<?= $form->field($model, 'email')->input('email') ?>

它会通过在 yii\widgets\ActiveField::$template 中定义的表单字段来创建 <label>，<input> 以及其它的标签。 input 输入框的 name 属性会自动地根据 yii\base\Model::formName() 以及属性名来创建。例如，对于在上面的例子中 username 输入字段的 name 属性将是 LoginForm[username]。这种命名规则使所有属性的数组的登录表单在服务器端的 $_POST['LoginForm'] 数组中是可用的。

Tip: If you have only one model in a form and want to simplify the input names you may skip the array part by overriding the yii\base\Model::formName() method of the model to return an empty string. This can be useful for filter models used in the GridView to create nicer URLs.

指定模型的属性可以以更复杂的方式来完成。例如，当上传时，多个文件或选择多个项目的属性，可能需要一个数组值，你可以通过附加 [] 来指定它的属性名称：

// 允许多个文件被上传：
echo $form->field($model, 'uploadFile[]')->fileInput(['multiple'=>'multiple']);

// 允许进行选择多个项目：
echo $form->field($model, 'items[]')->checkboxList(['a' => 'Item A', 'b' => 'Item B', 'c' => 'Item C']);

命名表单元素，如提交按钮时要小心。在 jQuery 文档中有一些保留的名称，可能会导致冲突：

表单和它们的子元素不应该使用与表单的属性冲突的 input name 或 id，例如 submit，length，或者 method。要检查你的标签是否存在这些问题，一个完整的规则列表详见 DOMLint。

额外的 HTML 标签可以使用纯 HTML 或者 yii\helpers\Html-辅助类中的方法来添加到表单中，就如上面例子中的 yii\helpers\Html::submitButton()。

提示: 如果你正在你的应用程序中使用 Twitter Bootstrap CSS 你可以使用yii\bootstrap\ActiveForm 来代替 yii\widgets\ActiveForm。前者继承自后者并在生成表单字段时使用 Bootstrap 特有的样式。

提示：为了设计带星号的表单字段，你可以使用下面的 CSS：
div.required label:after {
    content: " *";
    color: red;
}

创建下拉列表

可以使用 ActiveForm 的 dropDownList() 方法来创建一个下拉列表：

use app\models\ProductCategory;

/* @var $this yii\web\View */
/* @var $form yii\widgets\ActiveForm */
/* @var $model app\models\Product */

echo $form->field($model, 'product_category')->dropdownList(
    ProductCategory::find()->select(['category_name', 'id'])->indexBy('id')->column(),
    ['prompt'=>'Select Category']
);

模型字段的值将被自动预先选定。

Working with Pjax

The yii\widgets\Pjax widget allows you to update a certain section of a page instead of reloading the entire page. You can use it to update only the form and replace its contents after the submission.

You can configure yii\widgets\Pjax::$formSelector to specify which form submission may trigger pjax. If not set, all forms with data-pjax attribute within the enclosed content of Pjax will trigger pjax requests.

use yii\widgets\Pjax;
use yii\widgets\ActiveForm;

Pjax::begin([
    // Pjax options
]);
    $form = ActiveForm::begin([
        'options' => ['data' => ['pjax' => true]],
        // more ActiveForm options
    ]);

        // ActiveForm content

    ActiveForm::end();
Pjax::end();

Tip: Be careful with the links inside the yii\widgets\Pjax widget since the response will also be rendered inside the widget. To prevent this, use the data-pjax="0" HTML attribute.

Values in Submit Buttons and File Upload

There are known issues using jQuery.serializeArray() when dealing with files and submit button values which won't be solved and are instead deprecated in favor of the FormData class introduced in HTML5.

That means the only official support for files and submit button values with ajax or using the yii\widgets\Pjax widget depends on the browser support for the FormData class.

8.1 KiB Raw Blame History

创建表单

创建下拉列表

Working with Pjax

Values in Submit Buttons and File Upload

延伸阅读

8.1 KiB

Raw Blame History