下拉字段

dropdown 字段会渲染一个带指定选项的下拉菜单。有多种方法可以提供下拉菜单选项，其中大多数涉及指定 options 值。

yaml

status_type:
    type: dropdown
    label: Blog Post Status
    options:
        draft: Draft
        published: Published
        archived: Archived

以下字段属性受支持且常用。

Property	Description
title	title for the form field.
placeholder	text to display when the field is empty.
default	a default value to use for new records.
comment	places a descriptive comment below the field.
options	available options for the dropdown, as an array.
optionsMethod	take options from a method defined on the model or as a static method, eg `Class::method`.
optionsPreset	take options from a preset list of defined options.
emptyOption	text to display when allowing an empty option.
showSearch	allow the user to search options. Default: `true`.
attributes	an associative array of attributes and values to apply to the select field, useful for specifying custom Select2 configuration (see below).

通常 options 被定义为键值对，其中值和标签是独立指定的。

yaml

status_type:
    label: Blog Post Status
    type: dropdown
    options:
        draft: Draft
        published: Published
        archived: Archived

您可以使用 default 属性来设置一个默认值，其中该值是选项的键。

yaml

status_type:
    label: Blog Post Status
    type: dropdown
    default: published

为了处理没有设置值的情况，你可以指定一个 emptyOption 值，以包含一个可以重新选择的空选项。

yaml

status:
    label: Blog Post Status
    type: dropdown
    emptyOption: -- no status --

或者您也可以使用 placeholder 选项来使用一个无法重新选择的“一次性”空白选项。

yaml

status:
    label: Blog Post Status
    type: dropdown
    placeholder: -- select a status --

默认情况下，下拉菜单具有搜索功能，允许快速选择值。这可以通过将 showSearch 选项设置为 false 来禁用。

yaml

status:
    label: Blog Post Status
    type: dropdown
    showSearch: false

动态选项

接下来的方法涉及在您的插件或应用程序代码库中使用模型类。如果省略 options 值，框架会期望在模型中定义一个名为 get*FieldName*Options 的方法。

使用下面的示例，模型类应具有 getStatusTypeOptions 方法。此方法的第一个参数是此字段的当前值，第二个是整个表单的当前数据对象。此方法应以 key => label 格式返回选项数组。

yaml

status_type:
    label: Blog Post Status
    type: dropdown

这是模型类方法的一个示例，它提供下拉选项。
请注意，方法名与首字母大写格式的列名匹配。

php

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

您也可以定义一个兜底方法，该方法在未定义专用方法名的情况下用作备用，并将用于模型的所有下拉字段类型。

此方法的第一个参数是字段名，第二个是该字段的当前值，第三个是整个表单的当前数据对象。它应该返回一个选项数组，格式为 key => label。

php

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

要使用自定义方法名，在 options 参数中显式指定它并且这会与模型中定义的方法名完全匹配。

在下一个示例中，listStatuses 方法应在模型类中定义。此方法接收与getDropdownOptions 方法相同的所有参数，并应返回一个选项数组，格式为**key => label**。

yaml

status:
    label: Blog Post Status
    type: dropdown
    options: listStatuses

这是一个提供下拉选项的模型类自定义方法的示例。

php

public function listStatuses($fieldName, $value, $formData)
{
    return ['published' => 'Published', ...];
}

为了给下拉字段中渲染的每个选项添加自定义图标，您可以将选项指定为多维数组，格式如下：**键 => [标签文本, 标签图标]**。

php

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

显示自定义颜色也受支持通过将选项指定为一个数组其格式为 键 => [标签文本, 标签颜色] 其中颜色是一个十六进制值以井号 (#) 开头。

php

public function listStatuses($fieldName, $value, $formData)
{
    return [
        'published' => ['Published', '#666666'],
        'unpublished' => ['Unpublished', '#ff9999'],
        'draft' => ['Draft', '#ff0000']
    ];
}

如果你想调用外部类上的方法，可以通过调用任何完全限定对象上的静态方法来完成。只需在 options 参数中将 ClassName::method 语法指定为字符串。

yaml

status:
    label: Blog Post Status
    type: dropdown
    options: MyAuthor\MyPlugin\Helpers\FormHelper::staticMethodOptions

这个示例展示了在任何辅助类上定义的静态方法。第一个参数是 Model 对象和第二个参数是表单字段定义。

php

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

为了使用选项组 (optgroup) 你可以指定子项使用一个详细的选项定义。在下面的示例中选项组的标签取自其值因此无需重复。 children 属性包含该组的选项并且只支持一个层级的选项。

php

public function getDetailedFieldOptions()
{
    return [
        'Option Group' => [
            'optgroup' => true,
            'children' => [
                1 => 'Option 1',
                2 => 'Option 2',
                // ...
            ]
        ],
    ];
}

自定义 Select2 配置

下拉字段使用 Select2 控件来渲染该字段。在某些情况下您可能希望为此字段指定自定义配置。这可以通过使用 attributes 属性以及 Select2 提供的数据属性配置来实现。

例如，你可以微调下拉菜单的自动补全行为。

yaml

attributes:
    data-handler: onGetClientOptions
    data-minimum-input-length: 3
    data-process-Results: true
    data-ajax--delay: 300

当与标签列表字段一起使用时，以下操作将在选中项目后保持下拉菜单打开。

yaml

categories:
    type: taglist
    attributes:
        data-close-on-select: false

另请参阅

下拉字段

dropdown 字段会渲染一个带指定选项的下拉菜单。有多种方法可以提供下拉菜单选项，其中大多数涉及指定 options 值。

yaml

status_type:
    type: dropdown
    label: Blog Post Status
    options:
        draft: Draft
        published: Published
        archived: Archived

以下字段属性受支持且常用。

Property	Description
title	title for the form field.
placeholder	text to display when the field is empty.
default	a default value to use for new records.
comment	places a descriptive comment below the field.
options	available options for the dropdown, as an array.
optionsMethod	take options from a method defined on the model or as a static method, eg `Class::method`.
optionsPreset	take options from a preset list of defined options.
emptyOption	text to display when allowing an empty option.
showSearch	allow the user to search options. Default: `true`.
attributes	an associative array of attributes and values to apply to the select field, useful for specifying custom Select2 configuration (see below).

通常 options 被定义为键值对，其中值和标签是独立指定的。

yaml

status_type:
    label: Blog Post Status
    type: dropdown
    options:
        draft: Draft
        published: Published
        archived: Archived

您可以使用 default 属性来设置一个默认值，其中该值是选项的键。

yaml

status_type:
    label: Blog Post Status
    type: dropdown
    default: published

为了处理没有设置值的情况，你可以指定一个 emptyOption 值，以包含一个可以重新选择的空选项。

yaml

status:
    label: Blog Post Status
    type: dropdown
    emptyOption: -- no status --

或者您也可以使用 placeholder 选项来使用一个无法重新选择的“一次性”空白选项。

yaml

status:
    label: Blog Post Status
    type: dropdown
    placeholder: -- select a status --

默认情况下，下拉菜单具有搜索功能，允许快速选择值。这可以通过将 showSearch 选项设置为 false 来禁用。

yaml

status:
    label: Blog Post Status
    type: dropdown
    showSearch: false

动态选项

接下来的方法涉及在您的插件或应用程序代码库中使用模型类。如果省略 options 值，框架会期望在模型中定义一个名为 get*FieldName*Options 的方法。

yaml

status_type:
    label: Blog Post Status
    type: dropdown

这是模型类方法的一个示例，它提供下拉选项。
请注意，方法名与首字母大写格式的列名匹配。

php

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

您也可以定义一个兜底方法，该方法在未定义专用方法名的情况下用作备用，并将用于模型的所有下拉字段类型。

此方法的第一个参数是字段名，第二个是该字段的当前值，第三个是整个表单的当前数据对象。它应该返回一个选项数组，格式为 key => label。

php

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

要使用自定义方法名，在 options 参数中显式指定它并且这会与模型中定义的方法名完全匹配。

yaml

status:
    label: Blog Post Status
    type: dropdown
    options: listStatuses

这是一个提供下拉选项的模型类自定义方法的示例。

php

public function listStatuses($fieldName, $value, $formData)
{
    return ['published' => 'Published', ...];
}

为了给下拉字段中渲染的每个选项添加自定义图标，您可以将选项指定为多维数组，格式如下：**键 => [标签文本, 标签图标]**。

php

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

显示自定义颜色也受支持通过将选项指定为一个数组其格式为 键 => [标签文本, 标签颜色] 其中颜色是一个十六进制值以井号 (#) 开头。

php

public function listStatuses($fieldName, $value, $formData)
{
    return [
        'published' => ['Published', '#666666'],
        'unpublished' => ['Unpublished', '#ff9999'],
        'draft' => ['Draft', '#ff0000']
    ];
}

如果你想调用外部类上的方法，可以通过调用任何完全限定对象上的静态方法来完成。只需在 options 参数中将 ClassName::method 语法指定为字符串。

yaml

status:
    label: Blog Post Status
    type: dropdown
    options: MyAuthor\MyPlugin\Helpers\FormHelper::staticMethodOptions

这个示例展示了在任何辅助类上定义的静态方法。第一个参数是 Model 对象和第二个参数是表单字段定义。

php

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

php

public function getDetailedFieldOptions()
{
    return [
        'Option Group' => [
            'optgroup' => true,
            'children' => [
                1 => 'Option 1',
                2 => 'Option 2',
                // ...
            ]
        ],
    ];
}

自定义 Select2 配置

例如，你可以微调下拉菜单的自动补全行为。

yaml

attributes:
    data-handler: onGetClientOptions
    data-minimum-input-length: 3
    data-process-Results: true
    data-ajax--delay: 300

当与标签列表字段一起使用时，以下操作将在选中项目后保持下拉菜单打开。

yaml

categories:
    type: taglist
    attributes:
        data-close-on-select: false

文档导航

下拉字段

动态选项

自定义 Select2 配置

另请参阅

下拉字段

动态选项

自定义 Select2 配置

另请参阅