下拉字段

该 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

这是一个提供下拉选项的模型类方法的示例。请注意方法名称与列名称以 TitleCase 格式匹配。

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', ...];
}

为了给下拉字段中渲染的每个选项添加自定义图标，您可以将选项指定为一个多维数组，其格式为 key => [label-text, label-icon]。

php

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

显示自定义颜色也受支持，通过将选项指定为以下格式的数组：key => [label-text, label-color] 其中颜色是一个以 hash (#) 开头的十六进制值。

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

这是一个提供下拉选项的模型类方法的示例。请注意方法名称与列名称以 TitleCase 格式匹配。

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', ...];
}

为了给下拉字段中渲染的每个选项添加自定义图标，您可以将选项指定为一个多维数组，其格式为 key => [label-text, label-icon]。

php

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

显示自定义颜色也受支持，通过将选项指定为以下格式的数组：key => [label-text, label-color] 其中颜色是一个以 hash (#) 开头的十六进制值。

php

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

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 配置

参见