查询构造器

概述

查询构造器(Query Builder)允许你自定义一套复杂的条件，在表格中过滤数据。它能够处理无限嵌套条件，这就允许你使用 "and" 和 "or" 操作符进行分组。

要使用它，你需要定义一套用以过滤数据的"约束条件(constraints)"。Filament 包含了一些遵循通用数据类型的内置约束，不过你也可以自定义约束。

使用 QueryBuilder 过滤器，你可以将查询构造器添加到任何表格：

use Filament\Tables\Filters\QueryBuilder;
use Filament\Tables\Filters\QueryBuilder\Constraints\BooleanConstraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\DateConstraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\NumberConstraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint\Operators\IsRelatedToOperator;
use Filament\Tables\Filters\QueryBuilder\Constraints\SelectConstraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

QueryBuilder::make()
    ->constraints([
        TextConstraint::make('name'),
        BooleanConstraint::make('is_visible'),
        NumberConstraint::make('stock'),
        SelectConstraint::make('status')
            ->options([
                'draft' => 'Draft',
                'reviewing' => 'Reviewing',
                'published' => 'Published',
            ])
            ->multiple(),
        DateConstraint::make('created_at'),
        RelationshipConstraint::make('categories')
            ->multiple()
            ->selectable(
                IsRelatedToOperator::make()
                    ->titleAttribute('name')
                    ->searchable()
                    ->multiple(),
            ),
        NumberConstraint::make('reviewsRating')
            ->relationship('reviews', 'rating')
            ->integer(),
    ])

当深度嵌套查询构造器时，你可能需要增加过滤器占用的空间数量。其中一个方式是，将过滤器放在表格内容之上:

use Filament\Tables\Enums\FiltersLayout;
use Filament\Tables\Filters\QueryBuilder;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->filters([
            QueryBuilder::make()
                ->constraints([
                    // ...
                ]),
        ], layout: FiltersLayout::AboveContent);
}

可用约束

Filament 随附了许多开箱即用的约束。你也可以创建自定义约束：

• 文本约束
• 布尔值约束
• 数字约束
• 日期约束
• Select 约束
• 关联约束

文本约束

文本约束(Text constraints)允许你过滤文本字段。可用于过滤任何文本字段，包括通过关联来的文本。

use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

TextConstraint::make('name') // Filter the `name` column

TextConstraint::make('creatorName')
    ->relationship(name: 'creator', titleAttribute: 'name') // Filter the `name` column on the `creator` relationship

默认情况下，有如下一些可用操作符：

• Contains - 筛选包含搜索条件的字段
• Does not contain - 筛选不包含搜索条件的字段
• Starts with - 筛选以搜索条件为开头的列字段
• Does not start with - 筛选不以搜索条件为开头的列字段
• Ends with - 筛选以搜索条件为结尾的列字段
• Does not end with - 筛选不以搜索条件为结尾的列字段
• Equals - 筛选等于搜索词的列字段
• Does not equal - 筛选不等于搜索词的列字段
• Is filled - 筛选包含不为空的字段
• Is blank - 筛选包含值为空的字段

布尔值约束

布尔值约束(Boolean constraint)允许你过滤布尔值字段。可用于过滤任何布尔值字段，包括关联中的布尔值字段。

use Filament\Tables\Filters\QueryBuilder\Constraints\BooleanConstraint;

BooleanConstraint::make('is_visible') // Filter the `is_visible` column

BooleanConstraint::make('creatorIsAdmin')
    ->relationship(name: 'creator', titleAttribute: 'is_admin') // Filter the `is_admin` column on the `creator` relationship

默认情况下，以下操作符可用：

• Is true - 筛选值为 true 的字段
• Is false - 筛选值为 false 的字段

数值约束

数值约束(Number constraint)允许你过滤数值型字段。可用于过滤任何数值型字段，包括关联中的字段。

use Filament\Tables\Filters\QueryBuilder\Constraints\NumberConstraint;

NumberConstraint::make('stock') // Filter the `stock` column

NumberConstraint::make('ordersItemCount')
    ->relationship(name: 'orders', titleAttribute: 'item_count') // Filter the `item_count` column on the `orders` relationship

默认情况下，可以使用如下操作符：

• Is minimum - 筛选大于或等于所搜索数字的字段
• Is less than - 筛选小于所搜索数字的字段
• Is maximum - 筛选小于或等于所搜索数字的字段
• Is greater than - 筛选大于所搜索数字的字段
• Equals - 筛选等于所搜索数字的字段
• Does not equal - 筛选不等于所搜索数字的字段
• Is filled - 筛选不为空的字段
• Is blank - 筛选空值字段

使用 relationship() 中的数值约束时，用户也可以"聚合"关联记录。也就是说，可用过滤列字段一次性对所有关联记录求总和(sum)、求平均(average)、求最小值(minimum)或最大值(maximum)。

整型约束

默认情况下，数值约束允许小数值。如果你只想约束整型值，可以使用 integer() 方法：

use Filament\Tables\Filters\QueryBuilder\Constraints\NumberConstraint;

NumberConstraint::make('stock')
    ->integer()

日期约束

日期约束(Date constraint)允许你过滤日期字段。可用于过滤任何日期字段，包括关联日期字段。

use Filament\Tables\Filters\QueryBuilder\Constraints\DateConstraint;

DateConstraint::make('created_at') // Filter the `created_at` column

DateConstraint::make('creatorCreatedAt')
    ->relationship(name: 'creator', titleAttribute: 'created_at') // Filter the `created_at` column on the `creator` relationship

默认情况下，可以使用如下操作符：

• Is after - 过滤字段使之在搜索日期之后
• Is not after - 过滤字段使之不在搜索日期之后，包括同一日期
• Is before - 过滤字段使之在搜索日期之前
• Is not before - 过滤字段使之不在搜索日期之前，包括同一日期
• Is date - 过滤字段使之与搜索日期相同
• Is not date - 过滤字段使之不同于搜索日期
• Is month - 过滤字段使之与所选月份相同
• Is not month - 过滤字段使之与所选月份不同
• Is year - 过滤字段使之与所选年份相同
• Is not year - 过滤字段使之与所选年份不同

Select 约束

Select constraint 允许你使用 Select 字段过滤字段。可用于过滤任何字段，包括关联的字段。

use Filament\Tables\Filters\QueryBuilder\Constraints\SelectConstraint;

SelectConstraint::make('status') // Filter the `status` column
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    
SelectConstraint::make('creatorStatus')
    ->relationship(name: 'creator', titleAttribute: 'department') // Filter the `department` column on the `creator` relationship
    ->options([
        'sales' => 'Sales',
        'marketing' => 'Marketing',
        'engineering' => 'Engineering',
        'purchasing' => 'Purchasing',
    ])

可搜索 Select 约束

默认情况下，Select 约束不允许用户搜索选项。如果你想允许用户搜索选项，请使用 searchable() 方法：

use Filament\Tables\Filters\QueryBuilder\Constraints\SelectConstraint;

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

多选约束

默认情况下，Select Constraint 只允许用户选择一个选项。如果你想允许用户选择多个选项，请使用 multiple() 方法：

use Filament\Tables\Filters\QueryBuilder\Constraints\SelectConstraint;

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

当用户选择多个选项时，表格会过滤以显示匹配任何一个所选选项的记录。

关联约束

关联约束(Relationship constraint)允许你使用关联数据过滤字段：

use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint\Operators\IsRelatedToOperator;

RelationshipConstraint::make('creator') // Filter the `creator` relationship
    ->selectable(
        IsRelatedToOperator::make()
            ->titleAttribute('name')
            ->searchable()
            ->multiple(),
    )

IsRelatedToOperator 用于配置 "Is / Contains" 和 "Is not / Does not contain" 操作符。它提供了一个 Select 字段，允许用户过滤附加记录的关联。titleAttribute() 方法用于指定应使用哪个属性来识别列表中的每个关联记录。searchable() 方法使列表可搜索。multiple() 方法允许用户选择多个关联记录，如果选择了，表格将被过滤用以显示与所选任何关联记录匹配的记录。

多关联

默认情况下，关联约束只包含一个操作符，用于过滤单一关联，比如 BelongsTo。如果你使用 HasMany 或 BelongsToMany 这一的关联，你可以将约束标记为 multiple()：

use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint;

RelationshipConstraint::make('categories')
    ->multiple()

这会将如下操作符添加到约束：

• Has minimum - 过滤字段，使之至少有指定数量的关联记录
• Has less than - 过滤字段，使之拥有少于指定数量的关联记录
• Has maximum - 过滤字段，使之最多用有指定数量的关联记录
• Has more than - 过滤字段，使之拥有多于指定数量的关联记录
• Has - 过滤字段，使之拥有指定数量的关联记录
• Does not have - 过滤字段，使之没有指定数量的关联记录

空关联约束

RelationshipConstraint 和其他约束一样不支持 nullable()。

如果关联为 multiple()，那么约束会展示一个选项以过滤空关联。这意味着关联没有相关记录。如果关联是单一的，可以使用 emptyable() 方法展示一个用以过滤空关联的选项。

use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint;

RelationshipConstraint::make('creator')
    ->emptyable()

如果你的 multiple() 关联必须至少有一个关联记录，你可以使用 emptyable(false) 来因此过滤空关联的选项：

use Filament\Tables\Filters\QueryBuilder\Constraints\RelationshipConstraint;

RelationshipConstraint::make('categories')
    ->emptyable(false)

Nullable 约束

默认情况下，约束不会显示用于筛选 null 值的选项。如果你想显示筛选 null 值的选项，可以使用 nullable() 方法：

use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

TextConstraint::make('name')
    ->nullable()

以下是可用操作符：

• Is filled - 过滤字段使之非空
• Is blank - 过滤字段使之为空

关联查询范围设置

在约束中使用 relationship() 方法时，你可以使用 modifyQueryUsing` 参数设置查询范围，以过滤关联记录：

use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;
use Illuminate\Database\Eloquent\Builder;

TextConstraint::make('adminCreatorName')
    ->relationship(
        name: 'creator',
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->where('is_admin', true),
    )

自定义约束图标

每个约束类型都有一个默认的图标，它显示在选择器标签旁边。你可以将图标名传递给 icon() 方法自定义约束图标。

use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

TextConstraint::make('author')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->icon('heroicon-m-user')

重写默认操作符

每个约束都有一组默认的操作符，你可以使用 opearator() 方法对其进行自定义：

use Filament\Tables\Filters\QueryBuilder\Constraints\Operators\IsFilledOperator;
use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

TextConstraint::make('author')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->operators([
        IsFilledOperator::make(),
    ])

这将移除所有操作符，并注册 EqualsOperator。

如果你想将新操作符添加到列表尾部中，请使用 pushOperators()：

use Filament\Tables\Filters\QueryBuilder\Constraints\Operators\IsFilledOperator;
use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

TextConstraint::make('author')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->pushOperators([
        IsFilledOperator::class,
    ])

如果你想将新操作符添加到列表开头中，请使用 unshiftOperators()：

use Filament\Tables\Filters\QueryBuilder\Constraints\Operators\IsFilledOperator;
use Filament\Tables\Filters\QueryBuilder\Constraints\TextConstraint;

TextConstraint::make('author')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->unshiftOperators([
        IsFilledOperator::class,
    ])

创建自定义约束

使用Constraint::make() 方法，自定义约束可以和其他约束内联(inline)。你也可以将图标传递给 icon() 方法：

use Filament\Tables\Filters\QueryBuilder\Constraints\Constraint;

Constraint::make('subscribed')
    ->icon('heroicon-m-bell')
    ->operators([
        // ...
    ]),

如果你想自定义约束的标签，请使用 label() 方法：

use Filament\Tables\Filters\QueryBuilder\Constraints\Constraint;

Constraint::make('subscribed')
    ->label('Subscribed to updates')
    ->icon('heroicon-m-bell')
    ->operators([
        // ...
    ]),

现在，你必须为该约束定义操作符。你可以从这些选项中进行选择以过滤列字段。如果列字段是 nullable，你也可以为自定义约束注册内置运算符：

use Filament\Tables\Filters\QueryBuilder\Constraints\Constraint;
use Filament\Tables\Filters\QueryBuilder\Constraints\Operators\IsFilledOperator;

Constraint::make('subscribed')
    ->label('Subscribed to updates')
    ->icon('heroicon-m-bell')
    ->operators([
        // ...
        IsFilledOperator::class,
    ]),

创建自定义操作符

使用 Operator::make() 方法，可用创建自定义操作符：

use Filament\Tables\Filters\QueryBuilder\Constraints\Operators\Operator;

Operator::make('subscribed')
    ->label(fn (bool $isInverse): string => $isInverse ? 'Not subscribed' : 'Subscribed')
    ->summary(fn (bool $isInverse): string => $isInverse ? 'You are not subscribed' : 'You are subscribed')
    ->baseQuery(fn (Builder $query, bool $isInverse) => $query->{$isInverse ? 'whereDoesntHave' : 'whereHas'}(
        'subscriptions.user',
        fn (Builder $query) => $query->whereKey(auth()->user()),
    )),

本例中，操作符能够基于授权用户是否订阅该记录来过滤记录。订阅在表格的 subscriptions 关联中重新排序。

baseQuery() 方法用于定义过滤记录的查询。当选中"Subscribed" 选项时，$isInverse 参数为 false，而选中 Not subscribed 选项时，则为 true。该函数应用于表格的基础查询，其中可以使用 whereHas()。如果函数不需要应用到表格的基础查询，比如使用简单的 where() 或 whereIn()，你可以使用 query() 方法取代，它的好处是能够在嵌套的"OR"组中使用。

label() 方法用于渲染操作者选中的选项。每个操作者注册了两个选项，一个用于操作者未反转时，一个用在反转时。

当summary() 方法应用到查询时，它用在约束 header 中，以提供该激活约束的概览。

自定义约束选择器

在约束选择器中修改列数

约束选择器(Constraint Picker)只有 1 列。通过将列数传递给 constraintPickerColumns() 可以自定义列数：

use Filament\Tables\Filters\QueryBuilder;

QueryBuilder::make()
    ->constraintPickerColumns(2)
    ->constraints([
        // ...
    ])

该方法可以通过不同方式使用：

• 可以传递整型比如 constraintPickerColumns(2)。该整数为 lg 临界点及以上宽度时的 columns 数。比此小的设备，只会占 1 列。
• 你可以传递一个数组，其中键是临界点(breakpoint)、而值为列数。比如，constraintPickerColumns(['md' => 2, 'xl' => 4]) 将会在中等(medium)设备中创建 2 列布局，在超大设备中，创建 4 列布局。而较小(smaller)的设备的默认临界点使用 1 列布局，除非使用了 default 数组键。

临界点(sm、md、lg、xl、2xl)是由 Tailwind 定义，可以在 Tailwind 文档中查看。

增加约束选择器的宽度

当增加列数时，下拉列表的宽度应该逐步增加以处理额外的列数。如果您想要更多的控制，可以使用constraintPickerWidth() 方法手动设置下拉列表的最大宽度。选项对应于 Tailwind 的 max-width 刻度。可选宽度为'xs'、'sm'、'md'、'lg'、'xl'、'2xl'、'3xl'、4xl、'5xl'、6xl'、`7xl'：

use Filament\Tables\Filters\QueryBuilder;

QueryBuilder::make()
    ->constraintPickerColumns(3)
    ->constraintPickerWidth('2xl')
    ->constraints([
        // ...
    ])