表单字段

表单字段、表单UI和表单小部件是供表单使用的字段定义，例如文本输入。这些通常在以下领域中提及：

所有表单字段都根据其各自的类型属性进行识别。

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:
        # [...]

自定义字段类型

有各种原生字段类型可用于类型设置. 还可以通过指定表单字段部件的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

多个字段值

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

yaml

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

引用父级字段

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

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

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]

Additionally, if more than one caret ^ is used, it will refer that many levels higher: ^^grand_parent_field, ^^^grand_grand_parent_field, etc.

输入预设转换器

输入预设转换器通过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

表单字段

表单字段、表单UI和表单小部件是供表单使用的字段定义，例如文本输入。这些通常在以下领域中提及：

所有表单字段都根据其各自的类型属性进行识别。

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:
        # [...]

自定义字段类型

有各种原生字段类型可用于类型设置. 还可以通过指定表单字段部件的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

多个字段值

yaml

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

引用父级字段

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

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]

Additionally, if more than one caret ^ is used, it will refer that many levels higher: ^^grand_parent_field, ^^^grand_grand_parent_field, etc.

输入预设转换器

输入预设转换器通过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

文档导航

表单字段

可用字段

字段属性

选项卡属性

自定义字段类型

嵌套字段选择

字段门面

现场条件

触发事件

多个操作

多值条件

通配符值条件

多个字段值

引用父级字段

输入预设转换器

表单字段

可用字段

字段属性

选项卡属性

自定义字段类型

嵌套字段选择

字段门面

现场条件

触发事件

多个操作

多值条件

通配符值条件

多个字段值

引用父级字段

输入预设转换器