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),

getOptionLabelUsing() 至关重要，因为它为 Filament 提供了所选选项的标签，因此不需要执行完整的搜索来找到它。如果选项无效，则应返回 null。

#设置自定义加载消息

当用户使用可搜索 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.')

#设置自定义的“无选项”提示信息

当你在使用带有 preload() 或通过 options() 闭包提供动态选项的单选（select）或多选（multi-select）组件时，如果没有任何可用选项，你可能希望显示一条自定义提示信息。你可以使用 noOptionsMessage() 方法来实现这一点：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->preload()
    ->noOptionsMessage('No authors available.')

#设置自定义搜索提示

使用可搜索的 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
{
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            '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()),

getOptionLabelsUsing() 方法至关重要，因为它向 Filament 提供了已选中选项的标签，从而避免了执行全量搜索来查找这些选项。此外，它还用于验证用户所选选项的有效性；如果某个选项无效，则不应包含在 getOptionLabelsUsing() 返回的数组中。.

#重新排序选定选项

reorderable() 方法允许你对多选组件中选定的选项进行重新排序：

use Filament\Forms\Components\Select;

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

当所选选项的顺序很重要时，这非常有用。

#选项分组

你可以将选项分组到一个标签之下，以便更好地组织这些选项。为此，你可以传递分组数组到 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)),
    ])

#自定义多态关联的 Select 字段

You may further customize the “key” select field for a specific morph type using the modifyKeySelectUsing() method:

use Filament\Forms\Components\MorphToSelect;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\TextInput;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name')
            ->modifyKeySelectUsing(fn (Select $select): Select => $select
                ->createOptionForm([
                    TextInput::make('title')
                        ->required(),
                ])
                ->createOptionUsing(function (array $data): int {
                    return Product::create($data)->getKey();
                })),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])

This is useful if you want to customize the “key” select field for each morphed type individually. If you want to customize the key select for all types, you can use the modifyKeySelectUsing() method on the MorphToSelect component itself:

use Filament\Forms\Components\MorphToSelect;
use Filament\Forms\Components\Select;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name'),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])
    ->modifyKeySelectUsing(fn (Select $select): Select => $select->native())

You can also modify the “type” select field using the modifyTypeSelectUsing() method:

use Filament\Forms\Components\MorphToSelect;
use Filament\Forms\Components\Select;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name'),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])
    ->modifyTypeSelectUsing(fn (Select $select): Select => $select->native())

#Using toggle buttons for the type selector

By default, the type selector is a select field. You may switch it to use inline toggle buttons using the typeSelectToggleButtons() method:

use Filament\Forms\Components\MorphToSelect;

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

When using toggle buttons, you can customize them using the modifyTypeSelectUsing() method:

use Filament\Forms\Components\MorphToSelect;
use Filament\Forms\Components\ToggleButtons;

MorphToSelect::make('commentable')
    ->typeSelectToggleButtons()
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name'),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])
    ->modifyTypeSelectUsing(fn (ToggleButtons $toggleButtons): ToggleButtons => $toggleButtons->grouped())

#允许选项标签中使用 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())

#选项标签换行或截断

使用 JavaScript Select 组件时，超出 Select 元素宽度的标签默认会换行显示。你也可以选择截断溢出的标签。

use Filament\Forms\Components\Select;

Select::make('truncate')
    ->wrapOptionLabels(false)

#禁用占位符选择

使用 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')

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

使用 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 变慢且无响应。

#布尔值选项

如果你想要的是简单的布尔值 Select，带有“Yes”和“No”选项，你可以使用 boolean() 方法：

use Filament\Forms\Components\Select;

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

要自定义 Yes 标签，你可以在 boolean() 中使用 trueLabel 参数：

use Filament\Forms\Components\Select;

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

要自定义 No 标签，你可以在 boolean() 中使用 falseLabel 参数：

use Filament\Forms\Components\Select;

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

要自定义选项未被选中时的占位符，你可以在 boolean() 方法中使用 placeholder 参数：

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'),
    )

#自定义模态框表格 Select 的选项标签

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})")

默认情况下，multiple() 选项以“徽章”（badge）样式显示，而单个选项则以纯文本形式显示。可以使用 badge() 方法来指定选项标签是否应显示在徽章内：

use Filament\Forms\Components\ModalTableSelect;

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

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

badgeColor() 方法可用于设置徽标的颜色：

use Filament\Forms\Components\ModalTableSelect;

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

#向模态选择框中的表格传递额外参数

你可以使用 tableArguments() 方法，将参数从表单传递给表格配置类。例如，这可用于根据之前填写的表单字段来修改表格的查询：

use Filament\Actions\Action;
use Filament\Forms\Components\ModalTableSelect;
use Filament\Schemas\Components\Utilities\Get;

ModalTableSelect::make('products')
    ->relationship('products', 'name')
    ->multiple()
    ->tableConfiguration(ProductsTable::class)
    ->tableArguments(function (Get $get): array {
        return [
            'category_id' => $get('category_id'),
            'budget_limit' => $get('budget'),
        ];
    })

在表格配置类中，你可以使用 $table->getArguments() 方法访问这些参数：

use Filament\Forms\Components\TableSelect\Livewire\TableSelectLivewireComponent;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;
use Filament\Tables\Table;

class ProductsTable
{
    public static function configure(Table $table): Table
    {
        return $table
            ->modifyQueryUsing(function (Builder $query) use ($table): Builder {
                $arguments = $table->getArguments();
            
                if ($categoryId = $arguments['category_id'] ?? null) {
                    $query->where('category_id', $categoryId);
                }
                
                if ($budgetLimit = $arguments['budget_limit'] ?? null) {
                    $query->where('price', '<=', $budgetLimit);
                }
                
                return $query;
            })
            ->columns([
                TextColumn::make('name'),
                TextColumn::make('price')
                    ->money(),
                TextColumn::make('category.name')
                    ->hidden(filled($table->getArguments()['category_id'])),
            ]);
    }
}

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

ModalTableSelect::make('products')
    ->relationship(
        name: 'products',
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->whereBelongsTo(auth()->user()),
    )
    ->multiple()
    ->tableConfiguration(ProductsTable::class)

#Select 验证

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

#有效选项验证 (in() 规则)

in() 规则确保用户无法选择不在选项列表中的选项。这是出于数据完整性目的的重要规则，因此 Filament 默认将其应用于所有选择字段。

由于“Select”字段填充选项的方式多种多样，且在许多情况下选项并非默认全部加载（而是需要通过搜索来获取），Filament 会通过是否存在有效的“选项标签”来判断所选值是否存在。此外，它还会检查该选项是否处于禁用状态。

如果你使用自定义搜索查询来获取选项，请务必定义 getOptionLabelUsing() 方法，以便 Filament 能够根据可用选项验证所选值：

use Filament\Forms\Components\Select;

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

如果选项无效，getOptionLabelUsing() 方法应返回 null，以便 Filament 能够判断所选值不在选项列表中；如果选项有效，则应返回该选项的标签。

如果使用的是 multiple() 选择框（多选），则应定义 getOptionLabelsUsing() 而不是 getOptionLabelUsing()。此时，回调函数接收的参数将是 $values（而非 $value），并且你需要返回一个包含标签及其对应值的 $key => $value 格式的数组：

use Filament\Forms\Components\Select;

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()),

如果你使用了 relationship() 方法，系统会自动为你定义 getOptionLabelUsing() 或 getOptionLabelsUsing() 方法，因此你无需为此操心。

#选中的选项数验证

通过设置 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