Select

#简介

Select 组件允许你从一个预定义选项列表中选择一个或多个值：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])

#启用 JavaScript 版 Select

默认情况下，Filament 使用原生 HTML5 的 Select。通过 native(false) 方法，你可以启用更多自定义的 JavaScript 版 Select：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->native(false)

#搜索选项

使用 searchable()，你可以启用搜索输入框，以允许用户更容易访问多选项：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->label('Author')
    ->options(User::query()->pluck('name', 'id'))
    ->searchable()

此外，你也可以传入一个布尔值以控制其是否是可搜索的：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->label('Author')
    ->options(User::query()->pluck('name', 'id'))
    ->searchable(FeatureFlag::active())

#返回自定义搜索结果

如果你有大量的选项，且希望基于数据搜索或者其他外部数据源填充这些选项，你可以使用 getSearchResultsUsing() 和 getOptionLabelUsing()，而不是 options()。

getSearchResultsUsing() 方法接受一个回调函数，该回调以 $key => $value 格式返回搜索结果。当前用户的搜索结果可以通过 $search 获得，你应该使用它来过滤结果。

getOptionLabelUsing() 方法接受一个回调函数，该回调将选中的选项的 $value 值转换成标签。这用于用户还未进行搜索时的表单首次加载，该标签用于显示当前选则的选项还不可用。

如果你想提供自定义搜索结果，则必须在 Select 上同时使用 getSearchResultsUsing() 和 getOptionLabelUsing()：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->searchable()
    ->getSearchResultsUsing(fn (string $search): array => User::query()
        ->where('name', 'like', "%{$search}%")
        ->limit(50)
        ->pluck('name', 'id')
        ->all())
    ->getOptionLabelUsing(fn ($value): ?string => User::find($value)?->name),

#设置自定义加载消息

当用户使用可搜索 Select 或多选时，你可能希望在选项加载时显示自定义消息，你可以使用 loadingMessage() 来实现：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->loadingMessage('Loading authors...')

#设置无搜索结果的消息

当用户使用可搜索 Select 或多选时，你可能希望在未找到搜索结果时显示自定义消息，你可以使用 noSearchResultsMessage() 方法来实现：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->noSearchResultsMessage('No authors found.')

#设置自定义搜索提示

使用可搜索的 Select 或者多选时，你可能希望在用户输入搜索条件时显示自定义消息。为此，请使用 searchPrompt() 方法：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable(['name', 'email'])
    ->searchPrompt('Search authors by their name or email address')

#设置自定义搜索消息

使用可搜索的 Select 或者多选时，你可能希望加载搜索结果时显示自定义消息。为此，请使用 searchingMessage() 方法：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->searchingMessage('Searching authors...')

#调整搜索抖动

默认情况下，当用户输入到可搜索的 Select 或多选 Select 时，Filament 会在搜索之前等待 1000 毫秒(1 秒)。如果用户持续输入到搜索框，搜索之间也会等待 1000 毫秒。你可以使用 searchDebounce() 方法，对此进行修改：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->searchDebounce(500)

请不要将抖动调整太低，因为这会导致由于从服务器检索选项的网络请求数量太高而使 Select 变得缓慢且响应较差。

#多选

Select 组件上的 multiple() 方法允许你从选项列表中选择多个值：

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple()
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])

此外，你也可以传入布尔值以控制该字段是否可多选：

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple(FeatureFlag::active())
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])

这些选项以 JSON 格式返回。如果你在 Eloquent 中保存，请确保添加 array cast 转换 到模型属性上：

use Illuminate\Database\Eloquent\Model;

class App extends Model
{
    protected $casts = [
        'technologies' => 'array',
    ];

    // ...
}

如果你返回自定义搜索结果，你应该定义 getOptionLabelsUsing() 而非 getOptionLabelUsing()。$values 将传入到回调中，而非 $value，你应该返回$key => $value 标签数组以及他们对应的值：

Select::make('technologies')
    ->multiple()
    ->searchable()
    ->getSearchResultsUsing(fn (string $search): array => Technology::query()
        ->where('name', 'like', "%{$search}%")
        ->limit(50)
        ->pluck('name', 'id')
        ->all())
    ->getOptionLabelsUsing(fn (array $values): array => Technology::query()
        ->whereIn('id', $values)
        ->pluck('name', 'id')
        ->all()),

#选项分组

你可以将选项分组到一个标签之下，以便更好地组织这些选项。为此，你可以传递分组数组到 options() 方法或者其他你传递选项数组的方法。数组的键用作分组的标签，而其值未该分组下的选项数组：

use Filament\Forms\Components\Select;

Select::make('status')
    ->searchable()
    ->options([
        'In Process' => [
            'draft' => 'Draft',
            'reviewing' => 'Reviewing',
        ],
        'Reviewed' => [
            'published' => 'Published',
            'rejected' => 'Rejected',
        ],
    ])

#集成 Eloquent 关联

你可以使用 Select() 的 relationship() 方法去配置 BelongsTo 关联，使之自动检索选项。titleAttribute 是用以生成每个选项标签的字段名：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')

multiple() 方法可以和 relationship() 一起组合使用，用以使用 BelongsToMany 关联。Filament 会自动从关联中加载选项，并且在表单提交后将其保存回关联的中间表。如果没有提供 name，Filament 将回使用关联名作为字段名：

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple()
    ->relationship(titleAttribute: 'name')

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple()
    ->disabled()
    ->relationship(titleAttribute: 'name')

#在多个列中搜索关联选项

默认情况下，如果 Select 也是可搜索的，Filament 将会基于关联的标题列返回关联的搜索结果。如果你想在多个列中搜索，你可以将列数组传递给 searchable() 方法：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable(['name', 'email'])

#预加载关联选项

如果你希望在页面加载时弹出可搜索的选项，而不是在用户搜索时才弹出选项，你可以使用 preload() 方法：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->preload()

此外，你也可以传入一个布尔值以控制输入是否预加载：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->preload(FeatureFlag::active())

#排除当前记录

当使用递归关联时，你可能希望从结果集中移除当前记录。

可以使用 ignoreRecord 参数实现该功能：

use Filament\Forms\Components\Select;

Select::make('parent_id')
    ->relationship(name: 'parent', titleAttribute: 'name', ignoreRecord: true)

#自定义关联查询

使用 relationship() 的第三个参数，你可以自定义检索选项的数据库查询：

use Filament\Forms\Components\Select;
use Illuminate\Database\Eloquent\Builder;

Select::make('author_id')
    ->relationship(
        name: 'author',
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->withTrashed(),
    )

#自定义关联选项标签

如果你想为每个选项自定义标签，比如让其更有描述性，或者将姓和名组合起来，你可以在数据库迁移中使用虚拟(virtual)字段：

$table->string('full_name')->virtualAs('concat(first_name, \' \', last_name)');

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'full_name')

此外，你可以使用 getOptionLabelFromRecordUsing() 方法将选项的 Eloquent 模型转换成标签：

use Filament\Forms\Components\Select;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

Select::make('author_id')
    ->relationship(
        name: 'author',
        modifyQueryUsing: fn (Builder $query) => $query->orderBy('first_name')->orderBy('last_name'),
    )
    ->getOptionLabelFromRecordUsing(fn (Model $record) => "{$record->first_name} {$record->last_name}")
    ->searchable(['first_name', 'last_name'])

#保存中间数据到关联

如果你使用了 multiple() 关联，并且你的中间表有额外的列，你可以使用 pivotData() 方法来指定要保存到它们之中的数据：

use Filament\Forms\Components\Select;

Select::make('primaryTechnologies')
    ->relationship(name: 'technologies', titleAttribute: 'name')
    ->multiple()
    ->pivotData([
        'is_primary' => true,
    ])

#在模态框中创建新选项

你可以自定义用于创建新记录的表单，并将其附加到 BelongsTo 关联中：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->createOptionForm([
        Forms\Components\TextInput::make('name')
            ->required(),
        Forms\Components\TextInput::make('email')
            ->required()
            ->email(),
    ]),

该表单将在模态框中打开，用户可以在其中填写数据。表单提交之后，该字段会选中这个新记录。

#自定义新选项创建

使用 createOptionUsing() 方法，你可以自定义新选项的创建过程，该方法应该返回新记录的主键：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->createOptionForm([
       // ...
    ])
    ->createOptionUsing(function (array $data): int {
        return auth()->user()->team->members()->create($data)->getKey();
    }),

#模态框中编辑选中的选项

你可以自定义一个表单，用于编辑选中的记录，并将其保存回 BelongsTo 关联：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->editOptionForm([
        Forms\Components\TextInput::make('name')
            ->required(),
        Forms\Components\TextInput::make('email')
            ->required()
            ->email(),
    ]),

该表单将在模态框中打开，用户可以在其中填写数据。表单提交之后，表单中的数据会保存到记录中。

#自定义选项更新

你可以使用 updateOptionUsing() 方法自定义表单中所选选项的更新过程。当前正在编辑的 Eloquent 记录可以通过 Schema 中的 getRecord() 方法检索：

use Filament\Forms\Components\Select;
use Filament\Schemas\Schema;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->editOptionForm([
       // ...
    ])
    ->updateOptionUsing(function (array $data, Schema $schema) {
        $schema->getRecord()?->update($data);
    }),

#处理 MorphTo 关联

MorphTo 关联比较特别，因为它让用户可以从一系列不同模型中选择记录。因此，有一个专用的 MorphToSelect 组件，该组件实际上不是一个 Select 字段，而是在一个 Fieldset 里面的 2 个 Select 字段。第一个 Select 字段允许你选择类型，第二个允许你选择该类型下的记录。

要使用 MorphToSelect，你必须传入 types() 到组件中，以告知如何从不同类型中渲染选项：

use Filament\Forms\Components\MorphToSelect;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name'),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])

#自定义每个多态类型选项的标签

titleAttribute() 方法用于从每个产品/文章中提取标题。如果你想自定义每个选项的标签，你可以使用 getOptionLabelFromRecordUsing() 方法来将 Eloquent 模型转换成标签：

use Filament\Forms\Components\MorphToSelect;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->getOptionLabelFromRecordUsing(fn (Product $record): string => "{$record->name} - {$record->slug}"),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])

#自定义每个多态类型的关联查询

使用 modifyOptionsQueryUsing() 方法，你可以自定义检索选项的数据库查询：

use Filament\Forms\Components\MorphToSelect;
use Illuminate\Database\Eloquent\Builder;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name')
            ->modifyOptionsQueryUsing(fn (Builder $query) => $query->whereBelongsTo($this->team)),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title')
            ->modifyOptionsQueryUsing(fn (Builder $query) => $query->whereBelongsTo($this->team)),
    ])

#允许选项标签中使用 HTML

默认情况下，Filament 将转义选项标签中的 HTML。如果你希望允许使用 HTML，可以使用 allowHtml() 方法：

use Filament\Forms\Components\Select;

Select::make('technology')
    ->options([
        'tailwind' => '<span class="text-blue-500">Tailwind</span>',
        'alpine' => '<span class="text-green-500">Alpine</span>',
        'laravel' => '<span class="text-red-500">Laravel</span>',
        'livewire' => '<span class="text-pink-500">Livewire</span>',
    ])
    ->searchable()
    ->allowHtml()

此外，你也可以传入一个布尔值以控制输入是否允许 HTML：

use Filament\Forms\Components\Select;

Select::make('technology')
    ->options([
        'tailwind' => '<span class="text-blue-500">Tailwind</span>',
        'alpine' => '<span class="text-green-500">Alpine</span>',
        'laravel' => '<span class="text-red-500">Laravel</span>',
        'livewire' => '<span class="text-pink-500">Livewire</span>',
    ])
    ->searchable()
    ->allowHtml(FeatureFlag::active())

#禁用占位符选择

使用 selectablePlaceholder(false) 你可以防止占位符(空选项)被选中：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->default('draft')
    ->selectablePlaceholder(false)

#禁用指定选项

使用 disableOptionWhen() 方法，你可以禁用指定的选项。它接收一个闭包，在其中你可以检查指定的 $value 值的选项是否应该被禁用：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->default('draft')
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')

使用 getEnabledOptions()，你可以检索这些选项是否被禁用，比如出于验证需要：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->default('draft')
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')
    ->in(fn (Select $component): array => array_keys($component->getEnabledOptions()))

For more information about the in() function, please see the Validation documentation.

#字段旁边添加前后缀文本

使用 prefix() 和 suffix() 方法，你可以在输入框前后放置文本：

use Filament\Forms\Components\Select;

Select::make('domain')
    ->prefix('https://')
    ->suffix('.com')

#使用图标作为前后缀

使用 prefixIcon() 和 suffixIcon() 方法，你可以在输入框前后放置图标：

use Filament\Forms\Components\Select;
use Filament\Support\Icons\Heroicon;

Select::make('domain')
    ->suffixIcon(Heroicon::GlobeAlt)

#设置前后缀图标颜色

前后缀图标默认是灰色，不过你可以使用 prefixIconColor() 和 suffixIconColor() 方法将其设为不同颜色：

use Filament\Forms\Components\Select;
use Filament\Support\Icons\Heroicon;

Select::make('domain')
    ->suffixIcon(Heroicon::CheckCircle)
    ->suffixIconColor('success')

#限制选项数量

使用 optionsLimit() 方法，你可以限制显示在可搜索 Select 和多选 Select 中的选项数量。其默认值是 50：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->optionsLimit(20)

请确保不要将上限提得太高，因为这可能会因为浏览器内存占用太高而导致 Select 变慢且无响应。

#布尔值选项

If you want a simple boolean select, with “Yes” and “No” options, you can use the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean()

To customize the “Yes” label, you can use the trueLabel argument on the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean(trueLabel: 'Absolutely!')

To customize the “No” label, you can use the falseLabel argument on the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean(falseLabel: 'Not at all!')

To customize the placeholder that shows when an option has not yet been selected, you can use the placeholder argument on the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean(placeholder: 'Make your mind up...')

#从模态框中的表格选择选项

你可以使用 ModalTableSelect 组件在模态框中打开 Filament 表格，允许用户从中选择记录。当你的关联包含大量记录，并且希望用户能够执行高级筛选和搜索操作时，此功能非常有用。

要使用 ModalTableSelect，你必须拥有该模型的表格配置类。你可以使用 make:filament-table 命令生成这些类：

use Filament\Tables\Columns\TextColumn;
use Filament\Tables\Filters\SelectFilter;
use Filament\Tables\Table;

class CategoriesTable
{
    public static function configure(Table $table): Table
    {
        return $table
            ->columns([
                TextColumn::make('name')
                    ->searchable(),
                TextColumn::make('slug')
                    ->searchable(),
            ])
            ->filters([
                SelectFilter::make('parent')
                    ->relationship('parent', 'name')
                    ->searchable()
                    ->preload(),
            ]);
    }
}

该类必须又一个 configure() 方法，它接受并返回 Table 对象。其类名必须传递给 ModalTableSelect 组件的 tableConfiguration() 方法：

use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('category_id')
    ->relationship('category', 'name')
    ->tableConfiguration(CategoriesTable::class)

你也可以将 multiple() 方法与多重关联(例如 BelongsToMany)一起使用：

use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('categories')
    ->relationship('categories', 'name')
    ->multiple()
    ->tableConfiguration(CategoriesTable::class)

你可以使用 Action 对象配置方法自定义“选择”按钮和模态框。将函数传递给 selectAction() 方法允许你修改 $action 对象，例如，更改按钮标签和模态框标题：

use Filament\Actions\Action;
use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('category_id')
    ->relationship('category', 'name')
    ->tableConfiguration(CategoriesTable::class)
    ->selectAction(
        fn (Action $action) => $action
            ->label('Select a category')
            ->modalHeading('Search categories')
            ->modalSubmitActionLabel('Confirm selection'),
    )

getOptionLabelFromRecordUsing() 方法可用于自定义每个选定选项的标签。如果你想要显示更具描述性的标签或将两列连接在一起，这将非常有用：

use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('category_id')
    ->relationship('category', 'name')
    ->tableConfiguration(CategoriesTable::class)
    ->getOptionLabelFromRecordUsing(fn (Category $record): string => "{$record->name} ({$record->slug})")

#Select 验证

除了验证页面中列出的所有可用规则，有一些可以专门用于 Select 的规则。

#选中的选项验证

通过设置 minItems() 和 maxItems() 方法，你可以验证可以在多选 Select 中可以选择的最小和最大数量：

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple()
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
    ->minItems(1)
    ->maxItems(3)

#自定义 Select Action 对象

该字段使用 Action 对象，在其中对按钮进行自定义。通过传递一个函数到 Action 注册方法中，可以自定义这些按钮。该函数可以访问 $action 对象，用以自定义它或者自定义其模态框。下面是一些可以用于自定义 Action 的方法：

• createOptionAction()
• editOptionAction()
• manageOptionActions() (用于一次性自定义创建和编辑选项操作)

下面是一个如何自定义 Action 的示例：

use Filament\Actions\Action;
use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->createOptionAction(
        fn (Action $action) => $action->modalWidth('3xl'),
    )

Still need help? Join our Discord community or open a GitHub discussion