# 后台表单
### 介绍
**表单行为**是控制器修改器，用于轻松地将表单功能添加到后端页面。该行为提供了三个页面，分别称为“创建”，“更新”和“预览”。“预览”页面是“更新”页面的只读版本。当您使用表单行为时，无需在控制器中定义`create`，`update`和`preview`操作-该行为将为您完成。但是，您应该提供相应的视图文件。
表单行为取决于表单[字段定义](https://octobercms.com/docs/backend/forms#form-fields)和[模型类](https://octobercms.com/docs/database/model)。为了使用表单行为，您应该将其添加到`$implement`控制器类的属性中。另外，`$formConfig`应该定义class属性，并且其值应引用用于配置行为选项的YAML文件。
~~~
namespace Acme\Blog\Controllers;
class Categories extends \Backend\Classes\Controller
{
public $implement = ['Backend.Behaviors.FormController'];
public $formConfig = 'config_form.yaml';
}
~~~
> \*\*注意：\*\*通常，表单和[列表行为](https://octobercms.com/docs/backend/lists)在同一控制器中一起使用。
### [](https://octobercms.com/docs/backend/forms#configuring-form)配置表单行为
`$formConfig`属性中引用的配置文件以YAML格式定义。该文件应放置在控制器的[views目录中](https://octobercms.com/docs/backend/controllers-ajax/#introduction)。下面是一个典型的表单行为配置文件的示例：
~~~
# ===================================
# Form Behavior Config
# ===================================
name: Blog Category
form: $/acme/blog/models/post/fields.yaml
modelClass: Acme\Blog\Post
create:
title: New Blog Post
update:
title: Edit Blog Post
preview:
title: View Blog Post
~~~
表单配置文件中必须包含以下字段：
| 领域 | 描述 |
| --- | --- |
| **name** | 此表单管理的对象的名称。 |
| **form** | 配置数组或对表单域定义文件的引用，请参见[表单域](https://octobercms.com/docs/backend/forms#form-fields)。 |
| **modelClass** | 如果是模型类名称，则会针对此模型加载并保存表单数据。 |
下面列出的配置选项是可选的。如果您希望表单行为支持“[创建”](https://octobercms.com/docs/backend/forms#form-create-page)，“[更新”](https://octobercms.com/docs/backend/forms#form-update-page)或“[预览”](https://octobercms.com/docs/backend/forms#form-preview-page)页面，请定义它们。
| 选项 | 描述 |
| --- | --- |
| **defaultRedirect** | 未定义特定重定向页面时，用作后备重定向页面。 |
| **create** | 创建页面的配置数组或对配置文件的引用。 |
| **update** | 更新页面的配置数组或对配置文件的引用。 |
| **preview** | 预览页面的配置数组或对配置文件的引用。 |
### [](https://octobercms.com/docs/backend/forms#form-create-page)建立页面
要支持“创建”页面，请将以下配置添加到YAML文件：
~~~
create:
title: New Blog Post
redirect: acme/blog/posts/update/:id
redirectClose: acme/blog/posts
flashSave: Post has been created!
~~~
“创建”页面支持以下配置选项：
| 选项 | 描述 |
| --- | --- |
| **title** | 页面标题，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **redirect** | 保存记录时的重定向页面。 |
| **redirectClose** | 保存记录并且**关闭**后变量随请求一起发送时的重定向页面。 |
| **flashSave** | 保存记录时显示的Flash消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **form** | 仅覆盖创建页面的默认表单字段定义。 |
### [](https://octobercms.com/docs/backend/forms#form-update-page)更新页面
要支持“更新”页面，请在YAML文件中添加以下配置：
~~~
update:
title: Edit Blog Post
redirect: acme/blog/posts
flashSave: Post updated successfully!
flashDelete: Post has been deleted.
~~~
“更新”页面支持以下配置选项：
| 选项 | 描述 |
| --- | --- |
| **title** | 页面标题，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **redirect** | 保存记录时的重定向页面。 |
| **redirectClose** | 保存记录并**关闭**请求变量发送时的重定向页面。 |
| **flashSave** | 保存记录时显示的Flash消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **flashDelete** | 删除记录时显示的Flash消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **form** | 仅覆盖更新页面的默认表单字段定义。 |
### [](https://octobercms.com/docs/backend/forms#form-preview-page)预览页面
要支持“预览”页面，请在YAML文件中添加以下配置：
~~~
preview:
title: View Blog Post
~~~
“预览”页面支持以下配置选项：
| 选项 | 描述 |
| --- | --- |
| **title** | 页面标题，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **form** | 仅覆盖预览页面的默认表单字段定义。 |
### [](https://octobercms.com/docs/backend/forms#form-fields)定义表格栏位
表单字段是使用YAML文件定义的。表单行为使用表单字段配置来创建表单控件并将其绑定到模型字段。该文件放置在插件的**models**目录的子目录中。子目录名称与小写的模型类名称匹配。文件名无关紧要，但是**fields.yaml**和**form\_fields.yaml**是通用名称。表单字段示例文件位置：
~~~
plugins/
acme/
blog/
models/ <=== Plugin models directory
post/ <=== Model configuration directory
fields.yaml <=== Model form fields config file
Post.php <=== model class
~~~
字段可以放在三个区域中，即**外部区域**，**主选项卡**或**辅助选项卡**。下一个示例显示了表单字段定义文件的典型内容。
~~~
# ===================================
# Form Field Definitions
# ===================================
fields:
blog_title:
label: Blog Title
description: The title for this blog
published_at:
label: Published date
description: When this blog post was published
type: datepicker
[...]
tabs:
fields:
[...]
secondaryTabs:
fields:
[...]
~~~
可以使用“[关系小部件”](https://octobercms.com/docs/backend/forms#widget-relation)或“[关系管理器”](https://octobercms.com/docs/backend/relations#relationship-types)呈现相关模型中的字段。一个例外是OneToOne或morphOne相关字段，必须将其定义为related\*\*\[field\]\*\*，然后可以将其指定为模型的任何其他字段：
~~~
user_name:
label: User Name
description: The name of the user
avatar[name]:
label: Avatar
description: will be saved in the Avatar table
published_at:
label: Published date
description: When this blog post was published
type: datepicker
[...]
~~~
### [](https://octobercms.com/docs/backend/forms#form-tab-options)标签选项
对于每个选项卡定义（即`tabs`和）`secondaryTabs`，您可以指定以下选项：
| 选项 | 描述 |
| --- | --- |
| **stretch** | 指定此选项卡是否拉伸以适合父级高度。 |
| **defaultTab** | 分配字段的默认选项卡。默认值：其他。 |
| **icons** | 使用标签名称作为键将图标分配给标签。 |
| **lazy** | 单击时动态加载的选项卡数组。对于包含大量内容的选项卡很有用。 |
| **cssClass** | 为选项卡容器分配CSS类。 |
| **paneCssClass** | 将CSS类分配给单个选项卡窗格。值是一个数组，键是制表符索引或标签，值是CSS类。也可以将其指定为字符串，在这种情况下，该值将应用于所有选项卡。 |
> \*\*注意：\*\*建议不要在具有受触发器影响的字段的选项卡上使用延迟加载。
~~~
tabs:
stretch: true
defaultTab: User
cssClass: text-blue
lazy:
- Groups
paneCssClass:
0: first-tab
1: second-tab
icons:
User: icon-user
Groups: icon-group
fields:
username:
type: text
label: Username
tab: User
groups:
type: relation
label: Groups
tab: Groups
~~~
### [](https://octobercms.com/docs/backend/forms#form-field-options)栏位选项
您可以为每个字段指定以下选项（如果适用）：
| 选项 | 描述 |
| --- | --- |
| **label** | 向用户显示表单字段时的名称。 |
| **type** | 定义应如何呈现此字段（请参见下面的“[可用字段”类型](https://octobercms.com/docs/backend/forms#field-types)）。默认值：文本。 |
| **span** | 将表单字段对齐到一侧。选项：自动，左，右，风暴，满。默认值：完整。该参数`storm`允许您使用`cssClass`属性将表单显示为Bootstrap网格`cssClass: col-xs-4`。 |
| **size** | 指定使用它的字段的字段大小，例如textarea字段。选项：微小，较小，较大，巨大，巨型。 |
| **placeholder** | 如果该字段支持占位符值。 |
| **comment** | 在该字段下放置一个描述性注释。 |
| **commentAbove** | 在字段上方添加评论。 |
| **commentHtml** | 允许在注释内添加HTML标记。选项：true，false。 |
| **default** | 指定该字段的默认值。对于`dropdown`，`checkboxlist`，`radio`和`balloon-selector`窗口小部件，可以在此处指定一个选项键，把它选择默认。 |
| **defaultFrom** | 从另一个字段的值中获取默认值。 |
| **tab** | 将字段分配给选项卡。 |
| **cssClass** | 将CSS类分配给字段容器。 |
| **readOnly** | 防止修改字段。选项：true，false。 |
| **disabled** | 防止修改字段并将其从保存的数据中排除。选项：true，false。 |
| **hidden** | 从视图中隐藏该字段，并将其从保存的数据中排除。选项：true，false。 |
| **stretch** | 指定此字段是否拉伸以适合父级高度。 |
| **context** | 指定显示字段时应使用的上下文。也可以通过`@`在字段名称中使用符号来传递上下文，例如`name@update`。 |
| **dependsOn** | 此字段所[依赖](https://octobercms.com/docs/backend/forms#field-dependencies)的其他字段名称的数组，当修改其他字段时，此字段将更新。 |
| **trigger** | 使用[触发事件](https://octobercms.com/docs/backend/forms#field-trigger-events)为该字段指定条件。 |
| **preset** | 允许该字段值最初由另一个字段的值设置，并使用[输入预设转换器进行转换](https://octobercms.com/docs/backend/forms#field-input-preset)。 |
| **required** | 在字段标签旁边放置一个红色星号以指示它是必需的（请确保在模型上设置验证，因为这不是由表单控制器强制执行的）。 |
| **attributes** | 指定要添加到表单字段元素的自定义HTML属性。 |
| **containerAttributes** | 指定要添加到表单字段容器的自定义HTML属性。 |
| **permissions** | 当前后端用户必须具有的[权限](https://octobercms.com/docs/backend/users#users-and-permissions)才能使用该字段。支持单个权限的字符串或仅需要一个权限即可授予访问权限的一组权限。 |
### [](https://octobercms.com/docs/backend/forms#field-types)可用字段类型
有多种本机字段类型可用于**类型**设置。对于更高级的表单字段，可以使用[表单窗口小部件](https://octobercms.com/docs/backend/forms#form-widgets)来代替。
* [文本](https://octobercms.com/docs/backend/forms#field-text)
* [数](https://octobercms.com/docs/backend/forms#field-number)
* [密码](https://octobercms.com/docs/backend/forms#field-password)
* [电子邮件](https://octobercms.com/docs/backend/forms#field-email)
* [文字区](https://octobercms.com/docs/backend/forms#field-textarea)
* [落下](https://octobercms.com/docs/backend/forms#field-dropdown)
* [电台清单](https://octobercms.com/docs/backend/forms#field-radio)
* [气球选择器](https://octobercms.com/docs/backend/forms#field-balloon)
* [复选框](https://octobercms.com/docs/backend/forms#field-checkbox)
* [复选框清单](https://octobercms.com/docs/backend/forms#field-checkboxlist)
* [开关](https://octobercms.com/docs/backend/forms#field-switch)
* [部分](https://octobercms.com/docs/backend/forms#field-section)
* [部分的](https://octobercms.com/docs/backend/forms#field-partial)
* [暗示](https://octobercms.com/docs/backend/forms#field-hint)
* [小部件](https://octobercms.com/docs/backend/forms#field-widget)
### [](https://octobercms.com/docs/backend/forms#field-text)文本
`text`\-呈现单行文本框。如果未指定，则使用默认类型。
~~~
blog_title:
label: Blog Title
type: text
~~~
### [](https://octobercms.com/docs/backend/forms#field-number)数
`number`\-渲染仅包含数字的单行文本框。
~~~
your_age:
label: Your Age
type: number
step: 1 # defaults to 'any'
min: 1 # defaults to not present
max: 100 # defaults to not present
~~~
如果要在保存时在服务器端验证此字段以确保其为数字，请使用`$rules`模型上的属性，如下所示：
~~~
/**
* @var array Validation rules
*/
public $rules = [
'your_age' => 'numeric',
];
~~~
有关模型验证的更多信息，请访问[文档页面](https://octobercms.com/docs/services/validation#rule-numeric)。
### [](https://octobercms.com/docs/backend/forms#field-password)密码
`password`\-呈现单行密码字段。
~~~
user_password:
label: Password
type: password
~~~
### [](https://octobercms.com/docs/backend/forms#field-email)电子邮件
`email`\-呈现类型为的单行文本框`email`，从而触发移动浏览器中的电子邮件专用键盘。
~~~
user_email:
label: Email Address
type: email
~~~
如果您想在保存时验证此字段以确保它是格式正确的电子邮件地址，请使用`$rules`模型上的属性，如下所示：
~~~
/**
* @var array Validation rules
*/
public $rules = [
'user_email' => 'email',
];
~~~
有关模型验证的更多信息，请访问[文档页面](https://octobercms.com/docs/services/validation#rule-email)。
### [](https://octobercms.com/docs/backend/forms#field-textarea)文字区
`textarea`\-呈现多行文本框。还可以使用可能的值指定大小：微小，较小，较大，巨大，巨大。
~~~
blog_contents:
label: Contents
type: textarea
size: large
~~~
### [](https://octobercms.com/docs/backend/forms#field-dropdown)落下
`dropdown`\-使用指定的选项呈现下拉菜单。有6种方式提供下拉选项。
第一种方法`options`直接在YAML文件中定义（两个变体）：
（仅值）：
~~~
status_type:
label: Blog Post Status
type: dropdown
default: published
options:
draft
published
archived
~~~
（核心价值）：
~~~
status_type:
label: Blog Post Status
type: dropdown
default: published
options:
draft: Draft
published: Published
archived: Archived
~~~
第二种方法使用在模型类中声明的方法定义选项。如果省略options元素，则框架期望使用`get*FieldName*Options`在模型中定义名称的方法。使用上面的示例，模型应具有该`getStatusTypeOptions`方法。此方法的第一个参数是该字段的当前值，第二个参数是整个表单的当前数据对象。此方法应以格式**key => label**返回一个选项数组。
~~~
status_type:
label: Blog Post Status
type: dropdown
~~~
在模型类中提供下拉选项：
~~~
public function getStatusTypeOptions($value, $formData)
{
return ['all' => 'All', ...];
}
~~~
`getDropdownOptions`也可以在模型中定义第三个全局方法，该方法将用于模型的所有下拉字段类型。此方法的第一个参数是字段名称，第二个参数是字段的当前值，第三个参数是整个表单的当前数据对象。它应该以格式**key => label**返回一个选项数组。
~~~
public function getDropdownOptions($fieldName, $value, $formData)
{
if ($fieldName == 'status') {
return ['all' => 'All', ...];
}
else {
return ['' => '-- none --'];
}
}
~~~
第四个方法使用在模型类中声明的特定方法。在下一个示例中，`listStatuses`方法应在模型类中定义。此方法接收与该方法相同的所有参数`getDropdownOptions`，并应以格式**key => label**的形式返回选项数组。
~~~
status:
label: Blog Post Status
type: dropdown
options: listStatuses
~~~
为模型类提供下拉选项：
~~~
public function listStatuses($fieldName, $value, $formData)
{
return ['published' => 'Published', ...];
}
~~~
第五个方法允许您在类上指定静态方法以返回选项：
~~~
status:
label: Blog Post Status
type: dropdown
options: \MyAuthor\MyPlugin\Classes\FormHelper::staticMethodOptions
~~~
为模型类提供下拉选项：
~~~
public static function staticMethodOptions($fieldName, $value, $formData)
{
return ['published' => 'Published', ...];
}
~~~
第六个方法允许您通过数组定义指定可调用对象。如果使用PHP，则可以提供一个数组，其中第一个元素是对象，第二个元素是要在该对象上调用的方法。如果您使用的是YAML，则只能将静态方法定义为第二个元素，并将对类的命名空间引用作为第一个元素：
~~~
status:
label: Blog Post Status
type: dropdown
options: [\MyAuthor\MyPlugin\ClassesFormHelper, staticMethodOptions]
~~~
为模型类提供下拉选项：
~~~
public static function staticMethodOptions($fieldName, $value, $formData)
{
return ['published' => 'Published', ...];
}
~~~
要定义没有选择时的行为，您可以指定一个`emptyOption`值以包含可以重新选择的空选项。
~~~
status:
label: Blog Post Status
type: dropdown
emptyOption: -- no status --
~~~
或者，您可以使用该`placeholder`选项来使用无法单选的“单向”空选项。
~~~
status:
label: Blog Post Status
type: dropdown
placeholder: -- select a status --
~~~
默认情况下，下拉菜单具有搜索功能，可以快速选择一个值。可以通过将`showSearch`选项设置为禁用此功能`false`。
~~~
status:
label: Blog Post Status
type: dropdown
showSearch: false
~~~
### [](https://octobercms.com/docs/backend/forms#field-radio)电台清单
`radio`\-呈现一个单选选项列表，一次只能选择一项。
~~~
security_level:
label: Access Level
type: radio
default: guests
options:
all: All
registered: Registered only
guests: Guests only
~~~
单选列表还可以支持辅助描述。
~~~
security_level:
label: Access Level
type: radio
options:
all: [All, Guests and customers will be able to access this page.]
registered: [Registered only, Only logged in member will be able to access this page.]
guests: [Guests only, Only guest users will be able to access this page.]
~~~
单选列表支持将选项定义为[下拉字段类型](https://octobercms.com/docs/backend/forms#field-dropdown)的相同方法。对于单选列表，该方法可以返回简单数组：**key => value**或用于提供描述的数组数组：**key => \[label，description\]**。通过`cssClass: 'inline-options'`在单选字段配置中指定，选项可以彼此内联显示，而不是单独显示。
### [](https://octobercms.com/docs/backend/forms#field-balloon)气球选择器
`balloon-selector`\-呈现一个列表，一次只能选择一项。
~~~
gender:
label: Gender
type: balloon-selector
default: female
options:
female: Female
male: Male
~~~
气球选择器支持与[下拉字段类型](https://octobercms.com/docs/backend/forms#field-dropdown)相同的方法来定义选项。
### [](https://octobercms.com/docs/backend/forms#field-checkbox)复选框
`checkbox`\-呈现一个复选框。
~~~
show_content:
label: Display content
type: checkbox
default: true
~~~
### [](https://octobercms.com/docs/backend/forms#field-checkboxlist)复选框清单
`checkboxlist`\-呈现复选框列表。
~~~
permissions:
label: Permissions
type: checkboxlist
# set to true to explicitly enable the "Select All", "Select None" options
# on lists that have <=10 items (>10 automatically enables it)
quickselect: true
default: open_account
options:
open_account: Open account
close_account: Close account
modify_account: Modify account
~~~
复选框列表支持将选项定义为[下拉字段类型](https://octobercms.com/docs/backend/forms#field-dropdown)的相同方法，还支持在[单选字段类型中](https://octobercms.com/docs/backend/forms#field-radio)找到的辅助描述。通过`cssClass: 'inline-options'`在复选框列表字段config中指定，选项可以彼此内联显示，而不是单独显示。
### [](https://octobercms.com/docs/backend/forms#field-switch)开关
`switch`\-呈现一个开关箱。
~~~
show_content:
label: Display content
type: switch
comment: Flick this switch to display content
on: myauthor.myplugin::lang.models.mymodel.show_content.on
off: myauthor.myplugin::lang.models.mymodel.show_content.off
~~~
### [](https://octobercms.com/docs/backend/forms#field-section)部分
`section`\-呈现节标题和副标题。该`label`和`comment`值是可选的，包含标题和副标题的内容。
~~~
user_details_section:
label: User details
type: section
comment: This section contains details about the user.
~~~
### [](https://octobercms.com/docs/backend/forms#field-partial)部分的
`partial`\-渲染部分，该`path`值可以引用部分视图文件，否则，将字段名称用作部分名称。在部分变量中，这些变量可用：`$value`是默认字段值，`$model`是用于字段的模型，`$field`是配置的类对象`Backend\Classes\FormField`。
~~~
content:
type: partial
path: $/acme/blog/models/comments/_content_field.htm
~~~
### [](https://octobercms.com/docs/backend/forms#field-hint)暗示
`hint`\-与`partial`字段相同，但在提示容器内部呈现，用户可以将其隐藏。
~~~
content:
type: hint
path: content_field
~~~
### [](https://octobercms.com/docs/backend/forms#field-widget)小部件
`widget`\-呈现自定义表单窗口小部件，该`type`字段可以直接引用该窗口小部件的类名或注册的别名。
~~~
blog_content:
type: Backend\FormWidgets\RichEditor
size: huge
~~~
### [](https://octobercms.com/docs/backend/forms#validate-form-fields)验证表单字段
要验证表单的字段，您可以在模型中使用[Validation](https://octobercms.com/docs/database/traits#validation)特性。
- 基本说明
- 基本操作
- October cms 安装
- 后台控制器路径
- 图标
- 获取安装网上的插件/主题
- 插件构造器使用
- 定时任务
- October后台控制器
- vscode编辑器
- ajax操作
- 使用
- ajax更新组件
- ajax属性API
- JavaScript API
- ajax综合使用
- 主题
- 多语言主题
- 安装市场主题
- 主题程序处理
- 主题
- 页面
- 部件
- 布局
- 内容
- 组件
- 媒体
- 主题表单操作
- 表单使用
- 表单后端程序处理
- 插件
- 自定义插件
- 插件说明
- 插件导航条
- 插件数据库设置
- 插件的设置管理
- 插件的配置文件config
- 组件
- app服务
- app容器
- 扩展行为
- 缓存
- Collection类
- Lazy Collections
- Collection方法
- 助手函数
- 数组助手函数
- 路径助手函数
- 玄乐助手函数
- 其他助手函数
- 错误与记录
- 事件处理
- HTML页面
- 文件与目录操作
- 散列和加密
- 邮件
- 邮件内容
- 邮件发送
- 分页
- 模板解析器
- 动态解析器语法
- 队列消息
- 请求与输入
- 响应
- 视图
- 路由器
- 配置
- 验证操作
- 处理错误消息
- 错误消息与视图
- 可用的验证规则
- 有条件的验证规则
- 验证数组
- 错误消息
- 自定义验证规则
- 模型操作
- 定义模型与其属性
- 检索模型
- 插入与更新
- 删除模型
- 查询范围
- 事件操作
- 关联操作
- 定义关系
- 关系类型
- 多肽关系
- 关系查询
- 渴望加载
- 插入模型
- 数据库操作
- 基本用法
- 数据表结构
- 查询连贯操作
- 结果检索
- select子句
- 插入更新
- where子句
- 排序，分组，限制和偏移
- 文件附件
- Collection操作
- 属性操作
- 系列化json
- 数据库属性
- 数据库行为
- 控制器
- 后台控制器定义
- 后台页面
- 后台组件
- 后台表单
- 表单组件
- 表单视图
- 表单行为
- 后台列表
- 列表行为
- 列表过滤器
- 可用列类型
- 关系行为
- 关系行为类型
- 扩展关系行为
- 列表排序操作
- 导入导出操作
- 用于与权限
- corlate模板修改
- 修改顶部导航
- laravel问题
- 控制器不存在
- 控制器
- 路由组
- laravel笔记
- laravel 安装
- 伪静态配置
- 依赖注入 & 控制器
- 中间件
- 路由文件
- 视图