选择筛选器

简介

通常你会希望使用选择字段而不是复选框。尤其是当你要根据一组预定义选项筛选某列时。为此，可以使用 SelectFilter 类创建筛选器：

use Filament\Tables\Filters\SelectFilter;

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

传给筛选器的 options() 与传给选择字段的选项相同。

TIP

除静态值外，options() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

DANGER

options() 只是 UI 呈现手段，不是授权边界。选项列表限制下拉框显示的内容，但筛选器运行前不会对照该列表校验提交值。篡改 Livewire 请求的用户可以向筛选器状态提交任意值——apply() 会将其直接传入查询的 whereIn/where。

若你用 options() 向某类用户隐藏某些值（例如对非管理员隐藏 archived），应改为限定表格查询本身——例如使用 modifyQueryUsing() 或资源上的全局作用域——这样无论筛选器提交什么，受限制的行都不可达。

自定义选择筛选器使用的列

选择筛选器不需要自定义 query() 方法。用于限定查询范围的列名即为筛选器名称。要自定义它，可以使用 attribute() 方法：

use Filament\Tables\Filters\SelectFilter;

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

TIP

除静态值外，attribute() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

多选筛选器

这类筛选器允许用户选择多个选项来筛选表格。例如，状态筛选器可以向用户展示若干状态选项供选择并筛选表格。当用户选择多个选项时，表格会筛选出匹配任一所选选项的记录。可使用 multiple() 方法启用此行为：

use Filament\Tables\Filters\SelectFilter;

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

关联选择筛选器

选择筛选器也可以根据关联自动填充选项。例如，若表格有带 name 列的 author 关联，你可以使用 relationship() 筛选属于某作者的记录：

use Filament\Tables\Filters\SelectFilter;

SelectFilter::make('author')
    ->relationship('author', 'name')

预加载选择筛选器关联选项

若希望在页面加载时从数据库填充可搜索选项，而不是在用户搜索时再填充，可以使用 preload() 方法：

use Filament\Tables\Filters\SelectFilter;

SelectFilter::make('author')
    ->relationship('author', 'name')
    ->searchable()
    ->preload()

筛选空关联

默认情况下，选择某个选项后，所有关联为空的记录会被排除在结果之外。若想额外提供一个「None」选项供用户选择（包含所有没有关联的记录），可以使用 relationship() 方法的 hasEmptyOption() 参数：

use Filament\Tables\Filters\SelectFilter;

SelectFilter::make('author')
    ->relationship('author', 'name', hasEmptyOption: true)

你可以使用 emptyRelationshipOptionLabel() 方法重命名「None」选项：

use Filament\Tables\Filters\SelectFilter;

SelectFilter::make('author')
    ->relationship('author', 'name', hasEmptyOption: true)
    ->emptyRelationshipOptionLabel('No author')

自定义选择筛选器关联查询

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

use Filament\Tables\Filters\SelectFilter;
use Illuminate\Database\Eloquent\Builder;

SelectFilter::make('author')
    ->relationship('author', 'name', fn (Builder $query) => $query->withTrashed())

搜索选择筛选器选项

你可以使用 searchable() 方法启用搜索输入，以便更方便地访问大量选项：

use Filament\Tables\Filters\SelectFilter;

SelectFilter::make('author')
    ->relationship('author', 'name')
    ->searchable()

禁用占位符选择

你可以使用 selectablePlaceholder() 方法移除占位符（null 选项），从而禁用该「清空」能力，使筛选始终应用某个选项：

use Filament\Tables\Filters\SelectFilter;

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

默认应用选择筛选器

你可以使用 default() 方法将选择筛选器设为默认启用。若为单选筛选器，default() 接受单个选项值；若为 multiple() 多选筛选器，default() 接受选项值数组：

use Filament\Tables\Filters\SelectFilter;

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

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

TIP

除静态值外，default() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。