Filament 中文文档

主题

全部文档

分组行 ​

简介 ​

你可以允许用户使用共同属性将表格行分组在一起。这对以更有条理的方式展示大量数据很有用。

分组可以使用要按其分组的属性名来设置（例如 'status'），或使用允许你自定义该分组行为的 Group 对象（例如 Group::make('status')->collapsible()）。

默认分组行 ​

你可能希望始终按特定属性对文章分组。为此，将分组传给 defaultGroup() 方法：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->defaultGroup('status');
}
带分组的表格带分组的表格

设置默认分组方向 ​

默认情况下，分组按升序排列。若要默认使用降序，请向 defaultGroup() 方法传入 direction 参数：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->defaultGroup('status', direction: 'desc');
}

允许用户在分组间选择 ​

你也可以通过向 groups() 方法传入数组，允许用户在不同分组之间选择：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            'status',
            'category',
        ]);
}
带可选分组的表格带可选分组的表格

你可以同时使用 groups() 和 defaultGroup()，既允许用户在不同分组间选择，又设置默认分组：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            'status',
            'category',
        ])
        ->defaultGroup('status');
}

按关联属性分组 ​

你也可以使用点语法按关联属性分组。例如，若有带 name 属性的 author 关联，可以使用 author.name 作为属性名：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            'author.name',
        ]);
}

设置分组标签 ​

默认情况下，分组标签会根据属性生成。你可以使用 Group 对象的 label() 方法自定义：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('author.name')
                ->label('Author name'),
        ]);
}

设置分组标题 ​

默认情况下，分组标题为属性的值。你可以通过 Group 对象的 getTitleFromRecordUsing() 方法返回新标题来自定义：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->getTitleFromRecordUsing(fn (Post $record): string => ucfirst($record->status->getLabel())),
        ]);
}

禁用标题标签前缀 ​

默认情况下，标题会带有分组标签前缀。要禁用此前缀，请使用 titlePrefixedWithLabel(false) 方法：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->titlePrefixedWithLabel(false),
        ]);
}

设置分组描述 ​

你也可以为分组设置描述，它会显示在分组标题下方。为此，请在 Group 对象上使用 getDescriptionFromRecordUsing() 方法：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->getDescriptionFromRecordUsing(fn (Post $record): string => $record->status->getDescription()),
        ]);
}
带分组描述的表格带分组描述的表格

设置分组键 ​

默认情况下，分组的键为属性的值。它在内部用作该分组的原始标识符，而非标题。你可以通过 Group 对象的 getKeyFromRecordUsing() 方法返回新键来自定义：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->getKeyFromRecordUsing(fn (Post $record): string => $record->status->value),
        ]);
}

日期分组 ​

当使用日期时间列作为分组时，你可能希望仅按日期分组而忽略时间。为此，请在 Group 对象上使用 date() 方法：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('created_at')
                ->date(),
        ]);
}
带日期分组的表格带日期分组的表格

可折叠分组 ​

你可以允许分组内的行折叠到分组标题下方。要启用此功能，请使用带 collapsible() 方法的 Group 对象：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('author.name')
                ->collapsible(),
        ]);
}
带可折叠分组的表格带可折叠分组的表格

默认折叠分组 ​

默认情况下，带 collapsible() 方法的分组在表格加载时是展开的。

若希望表格加载时默认折叠所有分组，请使用 $table->collapsedGroupsByDefault()：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('author.name')
                ->collapsible(),
        ])
        ->collapsedGroupsByDefault();
}

汇总分组 ​

你可以在分组中使用汇总（summaries）来显示分组内记录的汇总。若你在已分组的表格列上添加了汇总器，此功能会自动生效。

隐藏分组行并仅显示汇总 ​

你可以使用 groupsOnly() 方法隐藏分组内的行，仅显示每个分组的汇总。这在许多报表场景中非常有用。

php
use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            TextColumn::make('views_count')
                ->summarize(Sum::make()),
            TextColumn::make('likes_count')
                ->summarize(Sum::make()),
        ])
        ->defaultGroup('category')
        ->groupsOnly();
}
仅分组模式的表格仅分组模式的表格

自定义 Eloquent 查询排序行为 ​

某些功能要求表格能够按分组对 Eloquent 查询排序。你可以使用 Group 对象上的 orderQueryUsing() 方法自定义此行为：

php
use Filament\Tables\Grouping\Group;
use Filament\Tables\Table;
use Illuminate\Database\Eloquent\Builder;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->orderQueryUsing(fn (Builder $query, string $direction) => $query->orderBy('status', $direction)),
        ]);
}

自定义 Eloquent 查询作用域行为 ​

某些功能要求表格能够按分组限定 Eloquent 查询作用域。你可以使用 Group 对象上的 scopeQueryByKeyUsing() 方法自定义此行为：

php
use Filament\Tables\Grouping\Group;
use Illuminate\Database\Eloquent\Builder;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->scopeQueryByKeyUsing(fn (Builder $query, string $key) => $query->where('status', $key)),
        ]);
}

自定义 Eloquent 查询分组行为 ​

某些功能要求表格能够按分组对 Eloquent 查询进行 group。你可以使用 Group 对象上的 groupQueryUsing() 方法自定义此行为：

php
use Filament\Tables\Grouping\Group;
use Illuminate\Database\Eloquent\Builder;

public function table(Table $table): Table
{
    return $table
        ->groups([
            Group::make('status')
                ->groupQueryUsing(fn (Builder $query) => $query->groupBy('status')),
        ]);
}

自定义分组下拉触发操作 ​

要自定义分组下拉触发按钮，可以使用 groupRecordsTriggerAction() 方法，传入返回操作的闭包。所有可用于自定义操作触发按钮的方法都可以使用：

php
use Filament\Actions\Action;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            // ...
        ])
        ->groupRecordsTriggerAction(
            fn (Action $action) => $action
                ->button()
                ->label('Group records'),
        );
}

在桌面端使用分组设置下拉框 ​

默认情况下，分组设置下拉框仅在移动设备上显示。在桌面设备上，分组设置位于表格页眉。你也可以使用 groupingSettingsInDropdownOnDesktop() 方法在桌面设备上启用该下拉框：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            // ...
        ])
        ->groupingSettingsInDropdownOnDesktop();
}

隐藏分组设置 ​

你可以使用 groupingSettingsHidden() 方法隐藏分组设置界面：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
		->defaultGroup('status')
        ->groupingSettingsHidden();
}

仅隐藏分组方向设置 ​

你可以使用 groupingDirectionSettingHidden() 方法隐藏分组方向选择界面：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
		->defaultGroup('status')
        ->groupingDirectionSettingHidden();
}

在用户会话中持久化分组 ​

要在用户会话中持久化分组，请使用 persistGroupInSession() 方法：

php
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->groups([
            'status',
            'category',
        ])
        ->persistGroupInSession();
}