表单字段

表单字段、表单用户界面和表单小部件是表单使用的字段定义，例如文本输入。这些通常由以下领域引用：

所有表单字段都被标识为其各自的类型属性。

yaml

fields:
    myfield:
        type: textarea
        # ...

表单字段包含通用和简单的字段。表单UI用于可以包含在表单中的用户界面元素，以帮助进行布局设计。表单小部件通常会引入更复杂的功能，插件通常会提供它们自己的自定义表单小部件。Tailor字段是仅在Tailor蓝图内部可用的字段。

可用字段

以下表单字段可用:

混合
 条目
 文本
 数字
 密码
 电子邮件
 文本区域
 下拉列表
 单选列表
 气球选择器
 复选框
 复选框列表
 开关
 代码编辑器
 颜色选择器
 数据表
 日期选择器
 文件上传
 Markdown编辑器
 媒体查找器
 嵌套表单
 记录查找器
 关联
 重复器
 富文本编辑器
 页面查找器
 敏感信息
 标签列表
 货币
 方框
 区块
 提示
 标尺
 局部

字段属性

对于每个字段，您可以指定这些通用属性，如适用。

Property	Description
label	a name when displaying the form field to the user.
type	defines how this field should be rendered. Default: `text`.
span	aligns the form field to one side. Options: `auto`, `left`, `right`, `row`, `full`. Default: `full`.
spanClass	used with the span `row` property to display the form as a Bootstrap grid, for example, `spanClass: col-4`.
size	specifies a field size for fields that use it, for example, the textarea field. Options: `tiny`, `small`, `large`, `huge`, `giant`.
placeholder	if the field supports a placeholder value.
comment	places a descriptive comment below the field.
commentAbove	places a comment above the field.
commentHtml	allow HTML markup inside the comment. Options: `true`, `false`.
default	specify the default value for the field. For `dropdown`, `checkboxlist`, `radio` and `balloon-selector` widgets, you may specify an option key here to have it selected by default.
defaultFrom	takes the default value from the value of another model attribute.
tab	assigns the field to a tab.
cssClass	assigns a CSS class to the field container.
autoFocus	flags the field to be focused when the form loads. Default: `false`.
readOnly	prevents the field from being modified. Options: `true`, `false`.
disabled	prevents the field from being modified and excludes it from the saved data. Options: `true`, `false`.
hidden	hides the field from the view and excludes it from the saved data. Options: `true`, `false`.
stretch	specifies if this field stretches to fit the parent height.
context	specifies what context should be used when displaying the field. Context can also be passed by using an `@` symbol in the field name, for example, `name@update`.
dependsOn	an array of other field names this field depends on, when the other fields are modified, this field will update.
changeHandler	the name of an AJAX handler to call when the field value is changed, optional.
trigger	specify conditions for this field using trigger events.
preset	allows the field value to be initially set by the value of another field, converted using the input preset converter.
required	places a red asterisk next to the field label to indicate it is required. Be sure to use the validation trait on the model as this is not enforced by the form controller.
attributes	specify custom HTML attributes to add to the form field element.
containerAttributes	specify custom HTML attributes to add to the form field container.
order	a numerical weight when determining the display order, default value increments at 100 points per field.
permissions	the permissions that the current backend user must have in order for the field to be used. Supports either a string for a single permission or an array of permissions of which only one is needed to grant access.

选项卡属性

一个在标签页中指定字段定义的示例。

yaml

tabs:
    fields:
        username:
            type: text
            label: Username
            tab: User

        groups:
            type: relation
            label: Groups
            tab: Groups

对于每个标签页定义，即 tabs 和 secondaryTabs，您可以指定这些属性。

Property	Description
stretch	specifies if this tab stretches to fit the parent height.
defaultTab	the default tab to assign fields to. Default: Misc.
activeTab	selected tab when the form first loads, name or index. Default: `1`
icons	assign icons to tabs using tab names as the key.
lazy	array of tabs to be loaded dynamically when clicked. Useful for tabs that contain large amounts of content.
identifiers	array of custom HTML identifiers for targeting the tab. Useful for showing and hiding tabs using JavaScript.
linkable	determines if the tabs can be linked using URL fragments. Default: `true`
cssClass	assigns a CSS class to the tab container.
paneCssClass	assigns a CSS class to an individual tab pane. Value is an array, key is tab index or label, value is the CSS class. It can also be specified as a string, in which case the value will be applied to all tabs.

一个将属性应用于标签页的示例。

yaml

tabs:
    stretch: true
    defaultTab: User
    cssClass: text-blue

    lazy:
        - Groups

    paneCssClass:
        1: first-tab
        2: second-tab

    icons:
        User: icon-user
        Groups: icon-group

    identifiers:
        User: userTab

    fields:
        # [...]

自定义字段类型

有多种原生字段类型可用于 type 设置. 也可以通过指定一个表单字段部件的 PHP 类名来直接渲染字段.

yaml

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

嵌套字段选择

yaml

avatar[name]:
    label: Avatar
    comment: will be saved in the Avatar table

上述示例将会获取并保存分别相当于 PHP 中 $record->avatar->name 或 $record->avatar['name'] 的值。

字段外观

有时你可能需要显示一个字段，同时阻止它被提交。一个字段可以通过在其名称前添加下划线（_）来定义为一个门面。这些字段会被自动清除，并且不再保存到模型中，例如以下 _map 字段。

yaml

address:
    label: Title
    type: text

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

现场条件

有时您可能希望在特定条件下操纵表单字段的值或外观，例如，如果您选中一个复选框，您可能希望隐藏一个输入框，或预设另一个字段的值。

触发事件

触发事件通过 trigger 表单字段属性定义，并且是一个使用 JavaScript 的简单基于浏览器的解决方案。它允许你根据其他元素的状态改变元素的属性，例如可见性或值。以下是一个示例定义：

yaml

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 定义指定了这些属性。

Property	Description
action	defines the action applied to this field when the condition is met. Supported values: `show`, `hide`, `enable`, `disable`, `empty`, `fill[somevalue]`.
field	reference to the other field name that triggers the action. Example: `color` or `color[]`.
condition	determines the condition the specified field should satisfy for the condition to be considered `true`. Supported values: `checked`, `unchecked`, `value[somevalue]`.

多项操作

您可以通过使用竖线 | 符号分隔来组合多个操作。当触发条件满足时，以下操作将同时显示并清空输入。

yaml

trigger:
    action: show|empty
    condition: checked
    field: name

多值条件

当使用 value[] 条件时，您可以通过在第一个值之后传递额外的值来查找多个值，其格式为 value[][]。

yaml

trigger:
    action: show
    condition: value[csv][csv_custom]
    field: file_format

通配符值条件

您可以检查 value[] 条件是否匹配多个可能值，方法是使用通配符 (*)，例如，foo* 匹配任何以 "foo" 开头的内容，而 *bar 匹配任何以 "bar" 结尾的内容。

yaml

trigger:
    action: show
    condition: value[*.mp4]
    field: file_name

该 value[] 可用于匹配空值。

yaml

trigger:
    action: show
    condition: value[]
    # ...

同样地，value[*] 条件可以用于匹配任何值。

yaml

trigger:
    action: show
    condition: value[*]
    # ...

多个字段值

某些字段，例如复选框列表和标签列表，将把它们的值存储为一个数组。引用这些字段时，字段名应使用数组后缀（[]）来查看所有可能的值。例如，如果一个colors字段名支持多个值，则字段名colors[]应作为引用使用。

yaml

trigger:
    action: show
    condition: value[red][green]
    field: colors[]

引用父字段

通常字段名指的是同一层级表单中的字段。例如，如果此字段位于一个重复器小部件中，只有该重复器小部件中的字段才会被检查。然而，如果字段名以脱字号 ^ 开头，例如：^parent_field，它将指的是比字段本身高一级的重复器小部件或表单。

在下面的例子中，colors 字段将会在 type 字段设置为 Complex 时显示。

yaml

fields:
    type:
        label: Type
        type: dropdown
        options:
            1: Simple
            2: Complex

    content:
        label: Content
        type: nestedform
        form:
            fields:
                colors:
                    label: Colors
                    type: colorpicker
                    trigger:
                        action: show
                        field: ^type
                        condition: value[2]

此外，如果使用多个插入符 ^，它将指代向上多层： ^^grand_parent_field， ^^^grand_grand_parent_field，等等。

输入预设转换器

输入预设转换器通过preset表单字段属性定义，并允许你将输入到某个元素中的文本转换为另一个输入元素中的URL、slug或文件名值。

在此示例中，当用户在 title 字段中输入文本时，我们将自动填充 url 字段的值。如果为 Title 输入文本 Hello world，URL 将随之变成转换后的值 /hello-world。此行为仅在目标字段 (url) 为空且未被修改时发生。

yaml

title:
    label: Title

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

或者，preset 值也可以是一个仅指代字段的字符串，此时 type 选项将默认设置为 slug。

yaml

slug:
    label: Slug
    preset: title

以下选项可用于preset选项：

Option	Description
field	defines the other field name to source the value from.
type	specifies the conversion type. See below for supported values.
prefixInput	optional, prefixes the converted value with the value found in the supplied input element using a CSS selector.

支持的类型如下：

Type	Description
exact	copies the exact value
slug	formats the copied value as a slug
url	same as slug but prefixed with a /
camel	formats the copied value with camelCase
file	formats the copied value as a file name with whitespace replaced with dashes

表单字段

表单字段、表单用户界面和表单小部件是表单使用的字段定义，例如文本输入。这些通常由以下领域引用：

所有表单字段都被标识为其各自的类型属性。

yaml

fields:
    myfield:
        type: textarea
        # ...

可用字段

以下表单字段可用:

字段属性

对于每个字段，您可以指定这些通用属性，如适用。

Property	Description
label	a name when displaying the form field to the user.
type	defines how this field should be rendered. Default: `text`.
span	aligns the form field to one side. Options: `auto`, `left`, `right`, `row`, `full`. Default: `full`.
spanClass	used with the span `row` property to display the form as a Bootstrap grid, for example, `spanClass: col-4`.
size	specifies a field size for fields that use it, for example, the textarea field. Options: `tiny`, `small`, `large`, `huge`, `giant`.
placeholder	if the field supports a placeholder value.
comment	places a descriptive comment below the field.
commentAbove	places a comment above the field.
commentHtml	allow HTML markup inside the comment. Options: `true`, `false`.
default	specify the default value for the field. For `dropdown`, `checkboxlist`, `radio` and `balloon-selector` widgets, you may specify an option key here to have it selected by default.
defaultFrom	takes the default value from the value of another model attribute.
tab	assigns the field to a tab.
cssClass	assigns a CSS class to the field container.
autoFocus	flags the field to be focused when the form loads. Default: `false`.
readOnly	prevents the field from being modified. Options: `true`, `false`.
disabled	prevents the field from being modified and excludes it from the saved data. Options: `true`, `false`.
hidden	hides the field from the view and excludes it from the saved data. Options: `true`, `false`.
stretch	specifies if this field stretches to fit the parent height.
context	specifies what context should be used when displaying the field. Context can also be passed by using an `@` symbol in the field name, for example, `name@update`.
dependsOn	an array of other field names this field depends on, when the other fields are modified, this field will update.
changeHandler	the name of an AJAX handler to call when the field value is changed, optional.
trigger	specify conditions for this field using trigger events.
preset	allows the field value to be initially set by the value of another field, converted using the input preset converter.
required	places a red asterisk next to the field label to indicate it is required. Be sure to use the validation trait on the model as this is not enforced by the form controller.
attributes	specify custom HTML attributes to add to the form field element.
containerAttributes	specify custom HTML attributes to add to the form field container.
order	a numerical weight when determining the display order, default value increments at 100 points per field.
permissions	the permissions that the current backend user must have in order for the field to be used. Supports either a string for a single permission or an array of permissions of which only one is needed to grant access.

选项卡属性

一个在标签页中指定字段定义的示例。

yaml

tabs:
    fields:
        username:
            type: text
            label: Username
            tab: User

        groups:
            type: relation
            label: Groups
            tab: Groups

对于每个标签页定义，即 tabs 和 secondaryTabs，您可以指定这些属性。

Property	Description
stretch	specifies if this tab stretches to fit the parent height.
defaultTab	the default tab to assign fields to. Default: Misc.
activeTab	selected tab when the form first loads, name or index. Default: `1`
icons	assign icons to tabs using tab names as the key.
lazy	array of tabs to be loaded dynamically when clicked. Useful for tabs that contain large amounts of content.
identifiers	array of custom HTML identifiers for targeting the tab. Useful for showing and hiding tabs using JavaScript.
linkable	determines if the tabs can be linked using URL fragments. Default: `true`
cssClass	assigns a CSS class to the tab container.
paneCssClass	assigns a CSS class to an individual tab pane. Value is an array, key is tab index or label, value is the CSS class. It can also be specified as a string, in which case the value will be applied to all tabs.

一个将属性应用于标签页的示例。

yaml

tabs:
    stretch: true
    defaultTab: User
    cssClass: text-blue

    lazy:
        - Groups

    paneCssClass:
        1: first-tab
        2: second-tab

    icons:
        User: icon-user
        Groups: icon-group

    identifiers:
        User: userTab

    fields:
        # [...]

自定义字段类型

有多种原生字段类型可用于 type 设置. 也可以通过指定一个表单字段部件的 PHP 类名来直接渲染字段.

yaml

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

嵌套字段选择

yaml

avatar[name]:
    label: Avatar
    comment: will be saved in the Avatar table

上述示例将会获取并保存分别相当于 PHP 中 $record->avatar->name 或 $record->avatar['name'] 的值。

字段外观

yaml

address:
    label: Title
    type: text

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

现场条件

有时您可能希望在特定条件下操纵表单字段的值或外观，例如，如果您选中一个复选框，您可能希望隐藏一个输入框，或预设另一个字段的值。

触发事件

yaml

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

trigger 定义指定了这些属性。

Property	Description
action	defines the action applied to this field when the condition is met. Supported values: `show`, `hide`, `enable`, `disable`, `empty`, `fill[somevalue]`.
field	reference to the other field name that triggers the action. Example: `color` or `color[]`.
condition	determines the condition the specified field should satisfy for the condition to be considered `true`. Supported values: `checked`, `unchecked`, `value[somevalue]`.

多项操作

您可以通过使用竖线 | 符号分隔来组合多个操作。当触发条件满足时，以下操作将同时显示并清空输入。

yaml

trigger:
    action: show|empty
    condition: checked
    field: name

多值条件

当使用 value[] 条件时，您可以通过在第一个值之后传递额外的值来查找多个值，其格式为 value[][]。

yaml

trigger:
    action: show
    condition: value[csv][csv_custom]
    field: file_format

通配符值条件

yaml

trigger:
    action: show
    condition: value[*.mp4]
    field: file_name

该 value[] 可用于匹配空值。

yaml

trigger:
    action: show
    condition: value[]
    # ...

同样地，value[*] 条件可以用于匹配任何值。

yaml

trigger:
    action: show
    condition: value[*]
    # ...

多个字段值

yaml

trigger:
    action: show
    condition: value[red][green]
    field: colors[]

引用父字段

在下面的例子中，colors 字段将会在 type 字段设置为 Complex 时显示。

yaml

fields:
    type:
        label: Type
        type: dropdown
        options:
            1: Simple
            2: Complex

    content:
        label: Content
        type: nestedform
        form:
            fields:
                colors:
                    label: Colors
                    type: colorpicker
                    trigger:
                        action: show
                        field: ^type
                        condition: value[2]

此外，如果使用多个插入符 ^，它将指代向上多层： ^^grand_parent_field， ^^^grand_grand_parent_field，等等。

输入预设转换器

输入预设转换器通过preset表单字段属性定义，并允许你将输入到某个元素中的文本转换为另一个输入元素中的URL、slug或文件名值。

yaml

title:
    label: Title

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

或者，preset 值也可以是一个仅指代字段的字符串，此时 type 选项将默认设置为 slug。

yaml

slug:
    label: Slug
    preset: title

以下选项可用于preset选项：

Option	Description
field	defines the other field name to source the value from.
type	specifies the conversion type. See below for supported values.
prefixInput	optional, prefixes the converted value with the value found in the supplied input element using a CSS selector.

支持的类型如下：

Type	Description
exact	copies the exact value
slug	formats the copied value as a slug
url	same as slug but prefixed with a /
camel	formats the copied value with camelCase
file	formats the copied value as a file name with whitespace replaced with dashes

文档导航

表单字段

可用字段

字段属性

选项卡属性

自定义字段类型

嵌套字段选择

字段外观

现场条件

触发事件

多项操作

多值条件

通配符值条件

多个字段值

引用父字段

输入预设转换器

表单字段

可用字段

字段属性

选项卡属性

自定义字段类型

嵌套字段选择

字段外观

现场条件

触发事件

多项操作

多值条件

通配符值条件

多个字段值

引用父字段

输入预设转换器