后台表格

• Introduction
• 配置表单行为
  • 创建页面
  • 更新页面
  • 预览页面
• 定义表单域
  • 选项卡选项
  • 字段选项
• 可用字段类型
• 表单小部件
• 表单视图
  • 创建视图
  • 更新视图
  • 预览视图
• 将条件应用于字段
  • 输入预设转换器
  • 触发事件
  • 字段依赖
  • 防止提交字段
• 扩展表单行为
  • 表单模型事件
  • 覆盖控制器动作
  • 覆盖控制器重定向
  • 扩展表单模型查询
  • 扩展表单域
  • 过滤表单域
• 验证表单域

#Introduction

这表单行为 是控制器behavior 用于轻松地将表单功能添加到后端页面。该行为提供了三个页面，分别称为创建、更新和预览。预览页面是更新页面的只读版本。当您使用表单行为时，您不需要定义create,update 和preview 控制器中的动作 - 行为会为您完成。但是您应该提供相应的视图文件。

表单行为取决于表单字段定义 和一个模型类.为了使用表单行为，你应该添加\Backend\Behaviors\FormController::class 的定义$implement 控制器类的属性。

namespace Acme\Blog\Controllers;

class Categories extends \Backend\Classes\Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\FormController::class,
    ];
}

NOTE: 很多时候形式和列表行为 在同一个控制器中一起使用。

#配置表单行为

表单行为将从一个 YAML 格式加载其配置config_form.yaml 文件位于控制器的查看目录 (plugins/myauthor/myplugin/controllers/mycontroller/config_form.yaml） 默认情况下。

这可以通过覆盖$formConfig 控制器上的属性以引用不同的文件名或完整的配置数组：

public $formConfig = 'my_custom_form_config.yaml';

下面是一个典型的表单行为配置文件的例子：

# ===================================
#  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

表单配置文件中需要以下字段：

下面列出的配置选项是可选的。如果您希望表单行为支持Create,Update 或者Preview 页。

#创建页面

要支持创建页面，请将以下配置添加到 YAML 文件中：

create:
    title: New Blog Post
    redirect: acme/blog/posts/update/:id
    redirectClose: acme/blog/posts
    flashSave: Post has been created!

创建页面支持以下配置选项：

#更新页面

要支持更新页面，请将以下配置添加到 YAML 文件中：

update:
    title: Edit Blog Post
    redirect: acme/blog/posts
    flashSave: Post updated successfully!
    flashDelete: Post has been deleted.

更新页面支持以下配置选项：

#预览页面

要支持预览页面，请将以下配置添加到 YAML 文件中：

preview:
    title: View Blog Post

预览页面支持以下配置选项：

#定义表单域

表单字段使用 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:
        [...]

来自相关模型的字段可以使用关系小部件 或者关系经理.例外是 OneToOne 或 morphOne 相关字段，必须定义为relation[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

    [...]

#选项卡选项

对于每个选项卡定义，即tabs 和secondaryTabs，您可以指定以下选项：

NOTE: 不建议在包含受触发器影响的字段的选项卡上使用延迟加载。

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

#字段选项

对于每个字段，您可以指定这些选项（如果适用）：

#可用字段类型

有多种本机字段类型可用于type 环境。对于更高级的表单域，一个表单小部件 可以代替使用。

#气球选择器

balloon-selector - 呈现一个列表，一次只能选择一个项目。

gender:
    label: Gender
    type: balloon-selector
    default: female
    options:
        female: Female
        male: Male

气球选择器支持与定义选项相同的方法下拉字段类型.

#Checkbox

checkbox - 呈现单个复选框。

show_content:
    label: Display content
    type: checkbox
    default: true

#复选框列表

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

复选框列表支持与定义选项相同的方法下拉字段类型 并且还支持二级描述，在无线电场类型.通过指定，选项可以相互内联显示，而不是在单独的行中cssClass: 'inline-options' 在复选框列表字段配置上。

#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

第二种方法使用模型类中声明的方法定义选项。如果省略选项元素，则框架需要一个名称为get*FieldName*Options 在模型中定义。使用上面的例子，模型应该有getStatusTypeOptions 方法。该方法的第一个参数是该字段的当前值，第二个参数是整个表单的当前数据对象。此方法应返回格式为的选项数组键=>标签.

status_type:
    label: Blog Post Status
    type: dropdown

在模型类中提供下拉选项：

public function getStatusTypeOptions($value, $formData)
{
    return ['all' => 'All', ...];
}

第三个全局方法getDropdownOptions 也可以在模型中定义，这将用于模型的所有下拉字段类型。这个方法的第一个参数是字段名，第二个是字段的当前值，第三个是整个表单的当前数据对象。它应该以格式返回一组选项键=>标签.

public function getDropdownOptions($fieldName, $value, $formData)
{
    if ($fieldName == 'status') {
        return ['all' => 'All', ...];
    }
    else {
        return ['' => '-- none --'];
    }
}

第四种方法使用模型类中声明的特定方法。在下一个例子中listStatuses 方法应该在模型类中定义。此方法接收与getDropdownOptions 方法，并且应该以格式返回一个选项数组键=>标签.

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($formWidget, $formField)
{
    return ['published' => 'Published', ...];
}

第六个方法允许您通过数组定义指定一个可调用对象。如果使用 PHP，您可以提供一个数组，其中第一个元素是对象，第二个元素是您要对该对象调用的方法。如果您使用的是 YAML，则仅限于定义为第二个元素的静态方法和对类的命名空间引用作为第一个元素：

status:
    label: Blog Post Status
    type: dropdown
    options: [\MyAuthor\MyPlugin\Classes\FormHelper, staticMethodOptions]

向模型类提供下拉选项：

public static function staticMethodOptions($formWidget, $formField)
{
    return ['published' => 'Published', ...];
}

#将图标添加到下拉选项

为了为将在下拉字段中呈现的每个选项添加图标或图像，必须将选项作为具有以下格式的多维数组提供'key' => ['label-text', 'icon-class'],.

public function listStatuses($fieldName, $value, $formData)
{
    return [
        'published' => ['Published', 'icon-check-circle'],
        'unpublished' => ['Unpublished', 'icon-minus-circle'],
        'draft' => ['Draft', 'icon-clock-o']
    ];
}

要定义没有选择时的行为，您可以指定一个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

#Email

email - 呈现类型为的单行文本框email，在移动浏览器中触发电子邮件专用键盘。

user_email:
    label: Email Address
    type: email

如果您想在保存时验证此字段以确保它是格式正确的电子邮件地址，请使用$rules 您模型上的属性，如下所示：

/**
 * @var array Validation rules
 */
public $rules = [
    'user_email' => 'email',
];

有关模型验证的更多信息，请访问文档页面.

#Hint

hint - 等同于partial 字段，但呈现在用户可以隐藏的提示容器内。

content:
    type: hint
    path: content_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',
];

有关模型验证的更多信息，请访问文档页面.

#Partial

partial - 呈现部分，path value 可以引用部分视图文件，否则字段名称将用作部分名称。在部分内部，这些变量可用：$value 是默认字段值，$model 是用于该字段的模型，并且$field 是配置的类对象Backend\Classes\FormField.

content:
    type: partial
    path: $/acme/blog/models/comments/_content_field.htm

NOTE: 如果您的部分字段仅用于显示并且不会向要存储的服务器提供值，那么最好在字段名称前加上下划线 (_)防止 FormController` 行为试图处理它

#Password

password - 呈现单行密码字段。也可以看看sensitive，对于应该能够根据要求披露的敏感数据。

user_password:
    label: Password
    type: password

#电台列表

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.]

单选列表支持与定义选项相同的方法下拉字段类型.对于单选列表，该方法可以返回简单数组：键=>值 或用于提供描述的数组数组：键=> [标签，描述].通过指定，选项可以相互内联显示，而不是在单独的行中cssClass: 'inline-options' 在无线电场配置上。

#Range

range - 呈现一个只接受数字的滑块。

your_age:
    label: Progress
    type: range
    step: 1  # defaults to 1
    min: 0   # defaults to 0
    max: 100 # defaults to 100

#Section

section - 呈现部分标题和副标题。这label 和comment 值是可选的，包含标题和副标题的内容。

user_details_section:
    label: User details
    type: section
    comment: This section contains details about the user.

#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

#Text

text - 呈现单行文本框。如果没有指定，这是默认使用的类型。

blog_title:
    label: Blog Title
    type: text

#Textarea

textarea - 呈现多行文本框。还可以使用可能的值指定大小：tiny,small,large,huge,giant.

blog_contents:
    label: Contents
    type: textarea
    size: large

#Widget

widget - 呈现自定义表单小部件，type 字段可以直接引用小部件的类名或注册的别名。

blog_content:
    type: Backend\FormWidgets\RichEditor
    size: huge

#表单小部件

标准包含各种表单小部件，尽管插件通常提供自己的自定义表单小部件。你可以阅读更多关于表单小部件 文章。

#代码编辑器

codeeditor - 为格式化代码或标记呈现纯文本编辑器。请注意，这些选项可能会被后台为管理员定义的代码编辑器首选项所继承。

css_content:
    type: codeeditor
    size: huge
    language: html

#选色器

colorpicker - 呈现控件以选择颜色值。

color:
    label: Background
    type: colorpicker

有两种方法可以为颜色选择器提供可用的颜色。第一种方法定义了availableColors 直接作为 YAML 文件中的颜色代码列表：

color:
    label: Background
    type: colorpicker
    availableColors: ['#000000', '#111111', '#222222']

第二种方法使用模型类中声明的特定方法。此方法应返回与上例格式相同的颜色数组。这个方法的第一个参数是字段名，第二个是字段的当前值，第三个是整个表单的当前数据对象。

color:
    label: Background
    type: colorpicker
    availableColors: myColorList

在模型类中提供可用的颜色：

public function myColorList($fieldName, $value, $formData)
{
    return ['#000000', '#111111', '#222222']
}

如果availableColors YAML 文件中未定义的字段，颜色选择器使用一组 20 种默认颜色。您还可以定义一组自定义的默认颜色，以用于所有没有availableColors 字段指定。这可以在自定义后端 设置区域。

#数据表

datatable - 呈现可编辑的记录表，格式为网格。单元格内容可以直接在网格中编辑，允许管理多行和多列信息。

NOTE: 为了将其与模型一起使用，该字段应定义为jsonable 属性，或作为另一个可以处理存储数组数据的属性。

data:
    type: datatable
    adding: true
    btnAddRowLabel: Add Row Above
    btnAddRowBelowLabel: Add Row Below
    btnDeleteRowLabel: Delete Row
    columns: []
    deleting: true
    dynamicHeight: true
    fieldName: null
    height: false
    keyFrom: id
    recordsPerPage: false
    searching: false
    toolbar: []

表格配置

下面列出了数据表控件本身的配置值。

列配置

数据表小部件允许通过columns 配置变量。每列都应该使用字段名作为键，并使用以下配置变量来设置字段。

Example:

columns:
    id:
        type: string
        title: ID
        validation:
            integer:
                message: Please enter a number
    name:
        type: string
        title: Name

列验证

可以针对以下类型的验证来验证列单元格。验证应指定为数组，验证类型用作键，可选消息指定为message 该验证的属性。

#日期选择器

datepicker - 呈现用于选择日期和时间的文本字段。

published_at:
    label: Published
    type: datepicker
    mode: date

#上传文件

fileupload - 呈现图像或常规文件的文件上传器。

avatar:
    label: Avatar
    type: fileupload
    mode: image
    imageHeight: 260
    imageWidth: 260
    thumbOptions:
        mode: crop
        offset:
            - 0
            - 0
        quality: 90
        sharpen: 0
        interlace: false
        extension: auto

NOTE: 不像媒体查找器表单小部件，文件上传 FormWidget 使用数据库文件附件;所以字段名必须匹配一个有效的attachOne 或者attachMany 与表单关联的模型上的关系。IMPORTANT: 具有此字段类型使用的名称的数据库列（即具有现有名称的数据库列attachOne 或者attachMany 关系）will 导致此 FormWidget 中断。将数据库列与 Media Finder FormWidget 结合使用，将文件附件关系与 File Upload FormWidget 结合使用。

#图标选取器

iconpicker - 呈现一个图标选择器，默认情况下由 WinterCMS 包含的 Font Awesome 图标提供支持。

icon:
    label: 'Icon'
    type: 'iconpicker'
    default: 'far icon-address-book'
    libraries: ~/modules/backend/formwidgets/iconpicker/meta/libraries.yaml

或者，您可以填充libraries 具有用户定义的库数组的属性（在下面的示例中far) 带有特定图标。

icon:
    label: 'Icon'
    type: 'iconpicker'
    default: 'far icon-address-book'
    libraries:
        -
            id: 'far'
            title: "Font Awesome Regular"
            prefix: "far icon-"
            listicon: "far icon-circle"
            icons:
                - "far icon-address-book"
                - "far icon-address-card"

NOTE: 如果不default 提供时，输入将保持为空，而图标选择器一旦加载，将集中在第一个可用图标上。

#降价编辑器

markdown - 呈现降价格式文本的基本编辑器。

md_content:
    type: markdown
    size: huge
    mode: split

#媒体查找器

mediafinder - 呈现用于从媒体管理器库中选择项目的字段。展开该字段会显示用于查找文件的媒体管理器。结果选择是一个字符串作为文件的相对路径。

background_image:
    label: Background image
    type: mediafinder
    mode: image

NOTE: 不像文件上传表单小组件, Media Finder FormWidget 将其数据存储为表示媒体库中所选图像路径的字符串。

#嵌套形式

nestedform - 将嵌套表单呈现为该字段的内容，并将表单数据作为数组返回。

NOTE: 为了将其与模型一起使用，该字段应定义为jsonable 属性，或作为另一个可以处理存储数组数据的属性。

content:
    type: nestedform
    usePanelStyles: false
    form:
        fields:
            added_at:
                label: Date added
                type: datepicker
            details:
                label: Details
                type: textarea
            title:
                label: This the title
                type: text
        tabs:
            meta_title:
                lable: Meta Title
                tab: SEO
            color:
                label: Color
                type: colorpicker
                tab: Design
        secondaryTabs:
            is_active:
                label: Active
                type: checkbox
            logo:
                label: Logo
                type: mediafinder
                mode: image

嵌套表单提供了一种整理可重用字段并使它们以多种形式可用的方法。嵌套表单支持与普通表单相同的语法，包括选项卡和辅助选项卡以及外部字段。嵌套表单的给定字段名称将包含嵌套表单的整个结构和值作为 JSON 数组。甚至可以在嵌套表单中使用嵌套表单。

#记录查找器

recordfinder - 呈现包含相关记录详细信息的字段。展开该字段会显示一个弹出列表以搜索大量记录。仅由单一关系支持。

user:
    label: User
    type: recordfinder
    list: ~/plugins/winter/user/models/user/columns.yaml
    recordsPerPage: 10
    title: Find Record
    prompt: Click the Find button to find a user
    keyFrom: id
    nameFrom: name
    descriptionFrom: email
    conditions: email = "bob@example.com"
    scope: whereActive
    searchMode: all
    searchScope: searchUsers
    useRelation: false
    modelClass: Winter\User\Models\User

#Relation

relation - 根据字段关系类型呈现下拉列表或复选框列表。单一关系显示一个下拉列表，多个关系显示一个复选框列表。用于显示每个关系的标签来源于nameFrom 或者select 定义。

categories:
    label: Categories
    type: relation
    nameFrom: title

或者，您可以使用自定义填充标签select 陈述。任何有效的 SQL 语句都适用于此。

user:
    label: User
    type: relation
    select: concat(first_name, ' ', last_name)

您还可以提供一个模型范围，用于过滤结果scope 财产。

#Repeater

repeater - 呈现其中定义的一组重复的表单字段。

extra_information:
    type: repeater
    titleFrom: title_when_collapsed
    form:
        fields:
            added_at:
                label: Date added
                type: datepicker
            details:
                label: Details
                type: textarea
            title_when_collapsed:
                label: This field is the title when collapsed
                type: text

转发器字段支持组模式，允许为每次迭代选择一组自定义字段。

content:
    type: repeater
    prompt: Add content block
    groups: $/acme/blog/config/repeater_fields.yaml

这是组配置文件的示例，该文件位于/plugins/acme/blog/config/repeater_fields.yaml.或者，这些定义可以与中继器内联指定。

textarea:
    name: Textarea
    description: Basic text field
    icon: icon-file-text-o
    fields:
        text_area:
            label: Text Content
            type: textarea
            size: large

quote:
    name: Quote
    description: Quote item
    icon: icon-quote-right
    fields:
        quote_position:
            span: auto
            label: Quote Position
            type: radio
            options:
                left: Left
                center: Center
                right: Right
        quote_content:
            span: auto
            label: Details
            type: textarea

每个组必须指定一个唯一的键，定义支持以下选项。

NOTE：组密钥与保存的数据一起存储为_group 属性。

直放站样式

这style 转发器小部件的属性控制转发器项目的行为。开发人员可以使用三种不同类型的样式：

• default: 显示在页面加载时展开的所有转发器项目。这是默认的当前行为，如果在转发器小部件的配置中未定义样式，将使用它。
• collapsed: 在页面加载时将所有转发器项目显示为折叠（最小化）。用户可以根据需要折叠或展开项目。
• accordion: 仅显示加载时展开的第一个中继器项目，所有其他中继器项目均已折叠。当另一个项目被展开时，任何其他展开的项目都会被折叠，有效地使它一次只能展开一个项目。

#丰富的编辑器/所见即所得

richeditor - 呈现丰富格式文本的可视化编辑器，也称为 WYSIWYG 编辑器。

html_content:
    type: richeditor
    toolbarButtons: bold|italic
    size: huge

可用的工具栏按钮有：

fullscreen, bold, italic, underline, strikeThrough, subscript, superscript, fontFamily, fontSize, |, color, emoticons, inlineStyle, paragraphStyle, |, paragraphFormat, align, formatOL, formatUL, outdent, indent, quote, insertHR, -, insertLink, insertImage, insertVideo, insertAudio, insertFile, insertTable, undo, redo, clearFormatting, selectAll, html

NOTE:| 将在工具栏中插入一条垂直分隔线，并且- 一个水平的。

#Sensitive

sensitive - 呈现可显示的密码字段，可用于敏感信息，如 API 密钥或机密、配置值等。敏感字段可根据用户请求切换可见和隐藏。

包含先前输入值的敏感字段将在加载时将值替换为占位符值，以防止根据长度猜测或复制该值。显示值后，原始值由 AJAX 检索并填充到字段中。

api_secret:
    type: sensitive
    allowCopy: false
    hideOnTabChange: true

#标签列表

taglist - 呈现用于输入标签列表的字段。

tags:
    type: taglist
    separator: space

标签列表支持与定义选项相同的方法下拉字段类型.

tags:
    type: taglist
    options:
        - Red
        - Blue
        - Orange

您可以使用mode 称为relation 其中字段名称是多对多关系.这将通过关系自动获取和分配标签。如果支持自定义标签，它们将在分配之前创建。

tags:
    type: taglist
    mode: relation

#表单视图

对于您的表单支持的每个页面Create,Update 和Preview 你应该提供一个查看文件 具有相应的名称 -create.htm,update.htm 和preview.htm.

表单行为向控制器类添加了两个方法：formRender 和formRenderPreview.这些方法呈现使用上述 YAML 文件配置的表单控件。

#创建视图

这create.htm 视图表示允许用户创建新记录的创建页面。典型的创建页面包含面包屑、表单本身和表单按钮。这data-request 属性应该是指onSave 表单行为提供的 AJAX 处理程序。下面是典型的 create.htm 表单的内容。

<?= Form::open(['class'=>'layout']) ?>

    <div class="layout-row">
        <?= $this->formRender() ?>
    </div>

    <div class="form-buttons">
        <div class="loading-indicator-container">
            <button
                type="button"
                data-request="onSave"
                data-request-data="close:true"
                data-hotkey="ctrl+enter, cmd+enter"
                data-load-indicator="Creating Category..."
                class="btn btn-default">
                Create and Close
            </button>
            <span class="btn-text">
                or <a href="<?= Backend::url('acme/blog/categories') ?>">Cancel</a>
            </span>
        </div>
    </div>

<?= Form::close() ?>

#更新视图

这update.htm 视图表示允许用户更新或删除现有记录的更新页面。典型的更新页面包含面包屑、表单本身和表单按钮。更新页面与创建页面非常相似，但通常有删除按钮。这data-request 属性应该是指onSave 表单行为提供的 AJAX 处理程序。下面是典型的 update.htm 表格的内容。

<?= Form::open(['class'=>'layout']) ?>

    <div class="layout-row">
        <?= $this->formRender() ?>
    </div>

    <div class="form-buttons">
        <div class="loading-indicator-container">
            <button
                type="button"
                data-request="onSave"
                data-request-data="close:true"
                data-hotkey="ctrl+enter, cmd+enter"
                data-load-indicator="Saving Category..."
                class="btn btn-default">
                Save and Close
            </button>
            <button
                type="button"
                class="wn-icon-trash-o btn-icon danger pull-right"
                data-request="onDelete"
                data-load-indicator="Deleting Category..."
                data-request-confirm="Do you really want to delete this category?">
            </button>
            <span class="btn-text">
                or <a href="<?= Backend::url('acme/blog/categories') ?>">Cancel</a>
            </span>
        </div>
    </div>

<?= Form::close() ?>

#预览视图

这preview.htm 视图表示允许用户以只读模式预览现有记录的预览页面。典型的预览页面包含面包屑和表单本身。下面是典型的 preview.htm 表单的内容。

<div class="form-preview">
    <?= $this->formRenderPreview() ?>
</div>

#将条件应用于字段

有时您可能希望在特定条件下操作表单字段的值或外观，例如，您可能希望在勾选复选框时隐藏输入。有几种方法可以做到这一点，可以使用触发器 API 或字段依赖项。输入预设转换器主要用于转换字段值。下面将更详细地描述这些选项。

#输入预设转换器

输入预设转换器定义为preset 表单域选项 并允许您将输入到元素中的文本转换为另一个输入元素中的 URL、slug 或文件名值。

在这个例子中，我们将自动填写url 用户在其中输入文本时的字段值title 场地。如果文字你好世界 为标题输入，URL 将跟随转换后的值/hello-world.只有当目标字段 (url) 是空的且未被触及。

title:
    label: Title

url:
    label: URL
    preset:
        field: title
        type: url

或者，preset value 也可以是引用的字符串field 只有type 然后选项将默认为slug.

slug:
    label: Slug
    preset: title

以下选项可用于preset 选项：

以下是支持的类型：

#触发事件

触发事件定义为trigger 表单域选项 并且是一个使用 JavaScript 的基于浏览器的简单解决方案。它允许您根据另一个元素的状态更改元素属性，例如可见性或值。这是一个示例定义：

is_delayed:
    label: Send later
    comment: Place a tick in this box if you want to send this message at a later time.
    type: checkbox

send_at:
    label: Send date
    type: datepicker
    cssClass: field-indent
    trigger:
        action: show
        field: is_delayed
        condition: checked

在上面的例子中send_at 只有当is_delayed 字段被选中。换句话说，如果另一个表单输入（字段）被选中（条件），该字段将显示（动作）。这trigger 定义指定了这些选项：

#字段依赖

表单字段可以通过定义声明对其他字段的依赖dependsOn 表单域选项 它提供了更强大的服务器端解决方案，用于在修改字段依赖项时更新字段。当声明为依赖项的字段发生变化时，定义字段将使用 AJAX 框架进行更新。这提供了一个机会，可以使用filterFields 方法或更改提供给该领域的可用选项。下面的例子：

country:
    label: Country
    type: dropdown

state:
    label: State
    type: dropdown
    dependsOn: country

在上面的例子中state 表单字段将在country 字段具有更改的值。发生这种情况时，当前表单数据将填充到模型中，以便下拉选项可以使用它。

public function getCountryOptions()
{
    return ['au' => 'Australia', 'ca' => 'Canada'];
}

public function getStateOptions()
{
    if ($this->country == 'au') {
        return ['act' => 'Capital Territory', 'qld' => 'Queensland', ...];
    }
    elseif ($this->country == 'ca') {
        return ['bc' => 'British Columbia', 'on' => 'Ontario', ...];
    }
}

此示例对于操作模型值很有用，但它无法访问表单字段定义。您可以通过定义一个filterFields 模型内部的方法，在过滤表单域 部分。下面提供了一个示例：

dnsprovider:
    label: DNS Provider
    type: dropdown

registrar:
    label: Registrar
    type: dropdown

specificfields[for][provider1]:
    label: Provider 1 ID
    type: text
    hidden: true
    dependsOn:
        - dnsprovider
        - registrar

specificfields[for][provider2]:
    label: Provider 2 ID
    type: text
    hidden: true
    dependsOn:
        - dnsprovider
        - registrar

filterFields 方法的逻辑如下：

public function filterFields($fields, $context = null)
{
    $displayedVendors = strtolower($this->dnsprovider->name . $this->registrar->name);
    if (str_contains($displayedVendors, 'provider1')) {
        $fields->{'specificfields[for][provider1]'}->hidden = false;
    }
    if (str_contains($displayedVendors, 'provider2')) {
        $fields->{'specificfields[for][provider2]'}->hidden = false;
    }
}

在上面的例子中，两个provider1 和provider2 无论何时，字段都会自动刷新dnsprovider或者registrar 字段被修改。发生这种情况时，将处理完整的表单循环，这意味着定义在filterFields 方法将再次运行，允许您过滤动态显示的字段。

#防止提交字段

有时您可能需要阻止提交字段。为此，只需在表单配置文件中的字段名称前添加一个下划线 (_)。以下划线开头的表单字段会自动清除，不再保存到模型中。

address:
    label: Title
    type: text

_map:
    label: Point your address on the map
    type: mapviewer

#扩展表单行为

有时您可能希望修改默认的表单行为，有几种方法可以做到这一点。

#表单模型事件

可以在生命周期的不同点调用多个控制器方法FormController 为自定义逻辑提供注入点。见API文档 以获得它们是什么的完整参考。一般来说，API 文档中的任何方法都带有前缀form 可以在您的控制器中重写以更改默认行为或充当自定义逻辑的注入点。

NOTE: 可能更希望使用模型事件 而是实施您的逻辑，因为无论与模型的交互发生在何处，如果模型受到影响，这些逻辑总是在适用时运行。

#覆盖控制器动作

您可以使用自己的逻辑create,update 或者preview 控制器中的 action 方法，然后可选地调用 Form 行为父方法。

public function update($recordId, $context = null)
{
    //
    // Do any custom code here
    //

    // Call the FormController behavior update() method
    return $this->asExtension('FormController')->update($recordId, $context);
}

#覆盖控制器重定向

您可以通过覆盖formGetRedirectUrl 方法。此方法返回重定向到的位置，相对 URL 被视为后端 URL。

public function formGetRedirectUrl($context = null, $model = null)
{
    return 'https://example.com';
}

#扩展模型查询

表单的查找查询数据库模型 可以通过重写来扩展formExtendQuery 控制器类中的方法。此示例将通过应用withTrashed 查询范围：

public function formExtendQuery($query)
{
    $query->withTrashed();
}

#扩展表单域

您可以通过调用从外部扩展另一个控制器的字段extendFormFields 控制器类上的静态方法。这个方法可以接受三个参数，$form 将代表表单小部件对象，$model 表示表单使用的模型和$context 是一个包含表单上下文的字符串。以这个控制器为例：

class Categories extends \Backend\Classes\Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\FormController::class,
    ];
}

使用extendFormFields 方法，您可以向此控制器呈现的任何表单添加额外的字段。由于这有可能影响该控制器使用的所有表单，因此最好检查$model 是正确的类型。这是一个例子：

Categories::extendFormFields(function($form, $model, $context)
{
    if (!$model instanceof MyModel) {
        return;
    }

    $form->addFields([
        'my_field' => [
            'label'   => 'My Field',
            'comment' => 'This is a custom field I have added.',
        ],
    ]);

});

您还可以通过覆盖formExtendFields 控制器类中的方法。这只会影响FormController 行为。

class Categories extends \Backend\Classes\Controller
{
    [...]

    public function formExtendFields($form)
    {
        $form->addFields([...]);
    }
}

$form 对象可以使用以下方法。

每个方法都采用类似于表单字段配置.

#过滤表单域

您可以通过覆盖filterFields 使用的模型内部的方法。这允许您根据模型数据操纵可见性和其他字段属性。该方法有两个参数$fields 将代表已经定义的字段的对象现场配置 和$context 表示活动表单上下文。

public function filterFields($fields, $context = null)
{
    if ($this->source_type == 'http') {
        $fields->source_url->hidden = false;
        $fields->git_branch->hidden = true;
    }
    elseif ($this->source_type == 'git') {
        $fields->source_url->hidden = false;
        $fields->git_branch->hidden = false;
    }
    else {
        $fields->source_url->hidden = true;
        $fields->git_branch->hidden = true;
    }
}

上面的例子将设置hidden 通过检查 Model 属性的值来标记某些字段source_type.此逻辑将在表单首次加载时以及由定义的字段依赖.

#验证表单域

要验证表单的字段，您可以使用Validation 模型中的特征。