Class yii\widgets\ActiveForm

继承yii\widgets\ActiveForm » yii\base\Widget » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable, yii\base\ViewContextInterface
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/widgets/ActiveForm.php

ActiveForm 是一个小部件, 可为一个或多个数据模型构建交互式 HTML 表单.

.

有关 ActiveForm 的更多详细信息和使用信息, 请参阅 权威指南 - 接收用户数据 - 创建表单(Creating Forms).

公共属性

隐藏继承的属性

属性类型描述定义在
$action array|string 表单提交的 URL. yii\widgets\ActiveForm
$ajaxDataType string 你期望从服务器返回的数据类型. yii\widgets\ActiveForm
$ajaxParam string 指示验证请求的 GET 参数的名称是 AJAX 请求. yii\widgets\ActiveForm
$attributes array 各种属性的客户端验证选项. yii\widgets\ActiveForm
$autoIdPrefix string 自动生成的小部件 ID 的前缀. yii\base\Widget
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$counter integer 用于为小部件生成 $id 的计数器. yii\base\Widget
$enableAjaxValidation boolean 是否启用基于 AJAX 的数据验证. yii\widgets\ActiveForm
$enableClientScript boolean 是否挂接`yii. yii\widgets\ActiveForm
$enableClientValidation boolean 是否启用客户端数据验证. yii\widgets\ActiveForm
$encodeErrorSummary boolean 是否对错误摘要执行编码. yii\widgets\ActiveForm
$errorCssClass string 当相关属性出现验证错误时, 添加到字段容器的 CSS 类. yii\widgets\ActiveForm
$errorSummaryCssClass string 错误摘要容器的默认 CSS 类. yii\widgets\ActiveForm
$fieldClass string 调用 field() 创建新字段时的默认字段类名称. yii\widgets\ActiveForm
$fieldConfig array|Closure 创建新字段对象时由 field() 使用的默认配置. yii\widgets\ActiveForm
$id string|null 小部件的 ID. Note: 此属性的类型在 getter 和 setter 中不同. 有关详细信息, 请参阅 getId()setId(). yii\base\Widget
$method string 表单提交方式. yii\widgets\ActiveForm
$options array 表单标签(form)的 HTML 属性(name-value 对). yii\widgets\ActiveForm
$requiredCssClass string 当相关属性是必填项时, 添加到字段容器的 CSS 类. yii\widgets\ActiveForm
$scrollToError boolean 验证后是否滚动到第一个错误. yii\widgets\ActiveForm
$scrollToErrorOffset integer 在滚动到第一个错误时应添加的像素偏移量. yii\widgets\ActiveForm
$stack yii\base\Widget[] 当前正在渲染的小部件(未结束). yii\base\Widget
$successCssClass string 当相关属性成功验证时, 添加到字段容器的 CSS 类. yii\widgets\ActiveForm
$validateOnBlur boolean 是否在输入字段失去焦点时执行验证. yii\widgets\ActiveForm
$validateOnChange boolean 是否在输入字段的值更改时执行验证. yii\widgets\ActiveForm
$validateOnSubmit boolean 是否在提交表单时执行验证. yii\widgets\ActiveForm
$validateOnType boolean 用户在输入字段中输入时是否执行验证. yii\widgets\ActiveForm
$validatingCssClass string 当相关属性被验证时, 添加到字段容器的 CSS 类. yii\widgets\ActiveForm
$validationDelay integer 当用户键入字段和 $validateOnType 设置为true时, 验证应延迟的毫秒数. yii\widgets\ActiveForm
$validationStateOn string 在哪里渲染验证状态类. yii\widgets\ActiveForm
$validationUrl array|string 用于执行基于 AJAX 的验证的 URL. yii\widgets\ActiveForm
$view yii\web\View 可用于渲染视图或视图文件的视图对象. Note: 此属性的类型在 getter 和 setter 中不同. 有关详细信息, 请参阅 getView()setView(). yii\base\Widget
$viewPath string 包含此小部件的视图文件的目录. 该属性是只读的. yii\base\Widget

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
afterRun() 在执行小部件后立即调用该方法. yii\base\Widget
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
beforeRun() 在执行小部件之前立即调用该方法. yii\base\Widget
begin() 开始一个小部件. yii\base\Widget
beginField() 开始一个表单域. yii\widgets\ActiveForm
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
end() 结束小部件. yii\base\Widget
endField() 结束一个表单域. yii\widgets\ActiveForm
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
errorSummary() 生成验证错误的摘要. yii\widgets\ActiveForm
field() 生成表单域. yii\widgets\ActiveForm
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getId() 返回小部件的 ID. yii\base\Widget
getView() 返回可用于渲染视图或视图文件的视图对象. yii\base\Widget
getViewPath() 返回包含此小部件的视图文件的目录. yii\base\Widget
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化小部件. yii\widgets\ActiveForm
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
registerClientScript() 注册必要的 JavaScript 代码. yii\widgets\ActiveForm
render() 渲染视图. yii\base\Widget
renderFile() 渲染视图文件. yii\base\Widget
run() 运行小部件. yii\widgets\ActiveForm
setId() 设置小部件的 ID. yii\base\Widget
setView() 设置此小部件要使用的视图对象. yii\base\Widget
trigger() 触发事件. yii\base\Component
validate() 验证一个或多个模型, 并返回由属性 ID 索引的错误消息数组. yii\widgets\ActiveForm
validateMultiple() 验证模型实例的数组, 并返回由属性 ID 索引的错误消息数组. yii\widgets\ActiveForm
widget() 创建一个小部件实例并运行它. yii\base\Widget

受保护的方法

隐藏继承的方法

方法描述定义在
getClientOptions() 返回表单 JS 小部件的配置选项. yii\widgets\ActiveForm

事件

隐藏继承的事件

事件类型描述定义在
EVENT_AFTER_RUN yii\base\WidgetEvent 在执行小部件之后立即触发的事件. (available since version 2.0.11) yii\base\Widget
EVENT_BEFORE_RUN yii\base\WidgetEvent 在执行小部件之前触发的事件. (available since version 2.0.11) yii\base\Widget
EVENT_INIT yii\base\Event 当通过 init() 初始化小部件时触发的事件. (available since version 2.0.11) yii\base\Widget

常量

隐藏继承的常量

常量描述定义在
VALIDATION_STATE_ON_CONTAINER 'container' 将验证状态类添加到容器标签. yii\widgets\ActiveForm
VALIDATION_STATE_ON_INPUT 'input' 将验证状态类添加到输入标签. yii\widgets\ActiveForm

属性详情

$action public 属性

表单提交的 URL. 此参数将由 yii\helpers\Url::to() 处理.

参见 $method 用于为此表单指定 HTTP 方法.

public array|string $action ''
$ajaxDataType public 属性

你期望从服务器返回的数据类型.

public string $ajaxDataType 'json'
$ajaxParam public 属性

指示验证请求的 GET 参数的名称是 AJAX 请求.

public string $ajaxParam 'ajax'
$attributes public 属性

各种属性的客户端验证选项.

数组中的每个元素表示特定属性的验证选项.

public array $attributes = []
$enableAjaxValidation public 属性

是否启用基于 AJAX 的数据验证.

如果设置了 yii\widgets\ActiveField::$enableAjaxValidation, 则该值将优先于该输入字段.

$enableClientScript public 属性

是否挂接yii.activeForm JavaScript 插件.

如果你想支持客户端验证和/或 AJAX 验证, 或者你想利用yii.activeForm插件, 则必须将此属性设置为true. 如果为false, 则表单将不会生成任何 JavaScript.

参见 registerClientScript().

$enableClientValidation public 属性

是否启用客户端数据验证.

如果设置了 yii\widgets\ActiveField::$enableClientValidation, 则该值将优先于该输入字段.

$encodeErrorSummary public 属性

是否对错误摘要执行编码.

$errorCssClass public 属性

当相关属性出现验证错误时, 添加到字段容器的 CSS 类.

public string $errorCssClass 'has-error'
$errorSummaryCssClass public 属性

错误摘要容器的默认 CSS 类.

参见 errorSummary().

public string $errorSummaryCssClass 'error-summary'
$fieldClass public 属性

调用 field() 创建新字段时的默认字段类名称.

参见 $fieldConfig.

public string $fieldClass 'yii\widgets\ActiveField'
$fieldConfig public 属性

创建新字段对象时由 field() 使用的默认配置.

这可以是配置数组或返回配置数组的匿名函数. 如果是后者, 则签名应如下所示:

function ($model, $attribute)

该属性的值将与传递给 field()$options 参数递归合并.

参见 $fieldClass.

$method public 属性

表单提交方式. 这应该是postget. 默认为post.

当你设置为get时, 你可能会看到每个请求都重复使用 URL 参数. 这是因为 $action 的默认值被设置为当前的请求 URL, 并且每个提交将添加新参数而不是替换现有参数. 你可以明确设置 $action 来避免这种情况:

$form = ActiveForm::begin([
    'method' => 'get',
    'action' => ['controller/action'],
]);
public string $method 'post'
$options public 属性

表单标签(form)的 HTML 属性(name-value 对).

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

public array $options = []
$requiredCssClass public 属性

当相关属性是必填项时, 添加到字段容器的 CSS 类.

public string $requiredCssClass 'required'
$scrollToError public 属性 (可用自版本: 2.0.6)

验证后是否滚动到第一个错误.

public boolean $scrollToError true
$scrollToErrorOffset public 属性 (可用自版本: 2.0.11)

在滚动到第一个错误时应添加的像素偏移量.

$successCssClass public 属性

当相关属性成功验证时, 添加到字段容器的 CSS 类.

public string $successCssClass 'has-success'
$validateOnBlur public 属性

是否在输入字段失去焦点时执行验证.

如果设置了 yii\widgets\ActiveField::$validateOnBlur, 则该值将优先于该输入字段.

public boolean $validateOnBlur true
$validateOnChange public 属性

是否在输入字段的值更改时执行验证.

如果设置了 yii\widgets\ActiveField::$validateOnChange, 则该值将优先于该输入字段.

public boolean $validateOnChange true
$validateOnSubmit public 属性

是否在提交表单时执行验证.

public boolean $validateOnSubmit true
$validateOnType public 属性

用户在输入字段中输入时是否执行验证.

如果设置了 yii\widgets\ActiveField::$validateOnType, 则该值将优先于该输入字段.

参见 $validationDelay.

public boolean $validateOnType false
$validatingCssClass public 属性

当相关属性被验证时, 添加到字段容器的 CSS 类.

public string $validatingCssClass 'validating'
$validationDelay public 属性

当用户键入字段和 $validateOnType 设置为true时, 验证应延迟的毫秒数.

如果设置了 yii\widgets\ActiveField::$validationDelay, 则该值将优先于该输入字段.

$validationStateOn public 属性 (可用自版本: 2.0.14)

在哪里渲染验证状态类. 可以是containerinput. 默认是container.

public string $validationStateOn self::VALIDATION_STATE_ON_CONTAINER
$validationUrl public 属性

用于执行基于 AJAX 的验证的 URL.

此属性将由 yii\helpers\Url::to() 处理. 有关如何配置此属性的更多详细信息, 请参阅 yii\helpers\Url::to().

如果未设置此属性, 则将使用表单的$action属性的值.

public array|string $validationUrl null

方法详情

beginField() public 方法

开始一个表单域.

此方法将创建一个新的表单域并返回其开始标签. 之后你应该调用 endField().

参见:

public string beginField ( $model, $attribute, $options = [] )
$model yii\base\Model

数据模型.

$attribute string

属性名称或表达式. 有关属性表达式的格式, 请参阅 yii\helpers\Html::getAttributeName().

$options array

字段对象的其它配置.

return string

开始标签.

endField() public 方法

结束一个表单域.

此方法将返回由 beginField() 启动的活动表单域的结束标签.

public string endField ( )
return string

表单域的结束标签.

throws yii\base\InvalidCallException

如果在没有先前 beginField() 调用的情况下调用此方法.

errorSummary() public 方法

生成验证错误的摘要.

如果没有验证错误, 则仍然会生成一个空的错误摘要标记, 但它将被隐藏.

参见 $errorSummaryCssClass.

public string errorSummary ( $models, $options = [] )
$models yii\base\Model|yii\base\Model[]

与此表单相关联的模型.

$options array

标签选项的 name-value 对. 以下选项被特别处理::

  • header: string, 错误摘要的标头 HTML. 如果未设置, 则将使用默认提示字符串.
  • footer: string, 错误摘要的页脚 HTML.

其余的选项将被渲染为容器标签的属性. 这些值将使用 yii\helpers\Html::encode() 进行 HTML 编码. 如果值为null, 则不会渲染相应的属性.

return string

生成的错误摘要.

field() public 方法

生成表单域.

表单域与模型和属性相关联. 它包含标签, 输入域和错误消息, 并使用它们与最终用户进行交互以收集其属性的输入.

参见 $fieldConfig.

public yii\widgets\ActiveField field ( $model, $attribute, $options = [] )
$model yii\base\Model

数据模型.

$attribute string

属性名称或表达式. 有关属性表达式的格式, 请参阅 yii\helpers\Html::getAttributeName().

$options array

字段对象的其它配置. 这些是 yii\widgets\ActiveField 或子类的属性, 具体取决于 $fieldClass 的值.

return yii\widgets\ActiveField

创建的 ActiveField 对象.

getClientOptions() protected 方法

返回表单 JS 小部件的配置选项.

protected array getClientOptions ( )
return array

配置选项.

init() public 方法

初始化小部件.

这会渲染表单开始标签.

public void init ( )
registerClientScript() public 方法 (可用自版本: 2.0.12)

注册必要的 JavaScript 代码.

public void registerClientScript ( )
run() public 方法

运行小部件.

这将注册必要的 JavaScript 代码, 并渲染表单的打开和关闭标签.

public void run ( )
throws yii\base\InvalidCallException

如果beginField()endField()调用不匹配.

validate() public static 方法

验证一个或多个模型, 并返回由属性 ID 索引的错误消息数组.

这是一个辅助方法, 可简化编写 AJAX 验证代码的方式.

例如, 你可以在控制器动作中使用以下代码来响应 AJAX 验证请求:

$model = new Post;
$model->load(Yii::$app->request->post());
if (Yii::$app->request->isAjax) {
    Yii::$app->response->format = Response::FORMAT_JSON;
    return ActiveForm::validate($model);
}
// ... 响应非 AJAX 请求 ...

要验证多个模型, 只需将每个模型作为参数传递给此方法, 如下所示:

ActiveForm::validate($model1, $model2, ...);
public static array validate ( $model, $attributes null )
$model yii\base\Model

要验证的模型.

$attributes mixed

应验证的属性列表. 如果此参数为空, 则表示应验证适用的验证规则中列出的所有属性. 当使用此方法验证多个模型时, 该参数将被解释为模型.

return array

由属性 ID 索引的错误消息数组.

validateMultiple() public static 方法

验证模型实例的数组, 并返回由属性 ID 索引的错误消息数组.

这是一个帮助方法, 它简化了为表格输入编写 AJAX 验证代码的方式.

例如, 你可以在控制器动作中使用以下代码来响应 AJAX 验证请求:

// ... load $models ...
if (Yii::$app->request->isAjax) {
    Yii::$app->response->format = Response::FORMAT_JSON;
    return ActiveForm::validateMultiple($models);
}
// ... 响应非 AJAX 请求 ...
public static array validateMultiple ( $models, $attributes null )
$models array

一系列要验证的模型.

$attributes mixed

应该验证的属性列表. 如果此参数为空, 则表示应验证适用的验证规则中列出的所有属性.

return array

由属性 ID 索引的错误消息数组.