汇总 - 表格构造器

概述

你可以在表格下面渲染一个汇总区域。这非常适合在表格中展示诸如平均值、总和、计数及数据范围这样的计算结果。

默认情况下，当前数据页将有一个汇总行，如果有多个页面可用，则会有一个额外的汇总行用于所有数据的汇总。你也可以为记录分组添加汇总，请查看"汇总行分组"。

使用 summarize() 方法，"汇总器(Summarizer)" 对象可以被添加到任何表格列中：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('rating')
    ->summarize(Average::make())
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('rating')
    ->summarize(Average::make())

可以将多个 "summarizer" 添加到同一个列：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('rating')
    ->numeric()
    ->summarize([
        Average::make(),
        Range::make(),
    ])
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('rating')
    ->numeric()
    ->summarize([
        Average::make(),
        Range::make(),
    ])

表格的第一个列不能使用汇总。该列用于摘要部分的标题和副标题。

可用汇总器

Filament 带有 4 中类型的汇总器：

平均值
计数
范围
总和

你也可以创建自定义汇总器。

Average

平均值(Average)可用于计算数据集中所有值的平均值：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('rating')
    ->summarize(Average::make())
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('rating')
    ->summarize(Average::make())

本例中，表格中所有的 rating 都会加总起来并除以 rating 的数量。

Count

计数(Count)可用于计算数据集的总数。除非你只想计算行数，你可能也需要设置数据集的范围：

use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\Summarizers\Count;
use Illuminate\Database\Query\Builder;
 
IconColumn::make('is_published')
    ->boolean()
    ->summarize(
        Count::make()->query(fn (Builder $query) => $query->where('is_published', true)),
    ),
use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\Summarizers\Count;
use Illuminate\Database\Query\Builder;

IconColumn::make('is_published')
    ->boolean()
    ->summarize(
        Count::make()->query(fn (Builder $query) => $query->where('is_published', true)),
    ),

本例中，表格将会计算发布了多少文章。

统计图标出现的次数

在图标列中使用计数，可以使用 icons() 方法，使用户对表格中每个图标的数量有一个直观的了解：

use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\Summarizers\Count;
use Illuminate\Database\Query\Builder;
 
IconColumn::make('is_published')
    ->boolean()
    ->summarize(Count::make()->icons()),
use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\Summarizers\Count;
use Illuminate\Database\Query\Builder;

IconColumn::make('is_published')
    ->boolean()
    ->summarize(Count::make()->icons()),

Range

范围(Range)可用于计算数据集中的最小值和最大值：

use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('price')
    ->summarize(Range::make())
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('price')
    ->summarize(Range::make())

本例中，可以看到表格中的最低价和最高价。

日期范围

使用 minimalDateTimeDifference() 方法，你可以将范围格式化为日期：

use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('created_at')
    ->dateTime()
    ->summarize(Range::make()->minimalDateTimeDifference())
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('created_at')
    ->dateTime()
    ->summarize(Range::make()->minimalDateTimeDifference())

该方法将会显示最小日期和最大日期之间的最小差异。比如：

如果最小日期和最大日期是不是同一天，则只会显示日期。
如果最小日期和最大日期是同一天的不同时间，日期和时间都会显示。
如果最小和最大日期和时间都是相同的，则只会显示一次。

文本范围

使用 minimalTextualDifference() 方法，你可以将范围格式化为文本：

use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('sku')
    ->summarize(Range::make()->minimalTextualDifference())
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('sku')
    ->summarize(Range::make()->minimalTextualDifference())

该方法将会显示最小值和最大值之间的最小差异。比如：

如果最小值和最大值以不同的字母开头，则只显示第一个字母。
如果最小值和最大值以同一个字母开头，则将呈现更多的文本，直到找到差异为止。
如果最小值和最大值相同，则它们只出现一次。

在范围中包含 null 值

默认情况下，我们会从范围中排除 null 值。如果你想将其包含进去，你可以使用 excludeNull(false) 方法：

use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('sku')
    ->summarize(Range::make()->excludeNull(false))
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('sku')
    ->summarize(Range::make()->excludeNull(false))

Sum

Sum 可用于计算数据集中所有值的总和：

use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('price')
    ->summarize(Sum::make())
use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('price')
    ->summarize(Sum::make())

本例中，表格中的所有价格会被相加起来。

设置标签

使用 label() 方法，可以设置汇总器标签

use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('price')
    ->summarize(Sum::make()->label('Total'))
use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('price')
    ->summarize(Sum::make()->label('Total'))

设置数据集范围

使用 query() 方法，你可以将数据库查询范围应用到汇总器数据集：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Query\Builder;
 
TextColumn::make('rating')
    ->summarize(
        Average::make()->query(fn (Builder $query) => $query->where('is_published', true)),
    ),
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Query\Builder;

TextColumn::make('rating')
    ->summarize(
        Average::make()->query(fn (Builder $query) => $query->where('is_published', true)),
    ),

本例中，只有 is_published 被设置为 true 的行数据会被用来计算平均值。

该特性对于 count 汇总器尤其有用，因为它可以统计数据集中有多少记录通过了测试：

use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\Summarizers\Count;
use Illuminate\Database\Query\Builder;
 
IconColumn::make('is_published')
    ->boolean()
    ->summarize(
        Count::make()->query(fn (Builder $query) => $query->where('is_published', true)),
    ),
use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\Summarizers\Count;
use Illuminate\Database\Query\Builder;

IconColumn::make('is_published')
    ->boolean()
    ->summarize(
        Count::make()->query(fn (Builder $query) => $query->where('is_published', true)),
    ),

本例中，表格对发布的文章数进行了统计。

格式化

数字格式化

numeric() 方法允许你将记录格式化为数字：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('rating')
    ->summarize(Average::make()->numeric())
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('rating')
    ->summarize(Average::make()->numeric())

如果你想自定义数字的精度用以格式化数字，你可以使用 decimalPlaces 参数：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('rating')
    ->summarize(Average::make()->numeric(
        decimalPlaces: 0,
    ))
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('rating')
    ->summarize(Average::make()->numeric(
        decimalPlaces: 0,
    ))

默认情况下，应用的本地化会将用于格式化数字。如果你想自定义使用的本地化，可以将其传递给 locale 参数：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('rating')
    ->summarize(Average::make()->numeric(
        locale: 'nl',
    ))
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('rating')
    ->summarize(Average::make()->numeric(
        locale: 'nl',
    ))

此外，你可以在服务提供者的 boot() 方法中，使用 Table::$defaultNumberLocale 方法，用以设置整个应用的默认本地化：

use Filament\Tables\Table;
 
Table::$defaultNumberLocale = 'nl';
use Filament\Tables\Table;

Table::$defaultNumberLocale = 'nl';

货币格式化

money() 方法允许你用任何货币将金额值进行格式化：

use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('price')
    ->summarize(Sum::make()->money('EUR'))
use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('price')
    ->summarize(Sum::make()->money('EUR'))

money() 还有一个 divideBy 参数，以允许你在格式化之前将原始值除以某个数字。这对在数据库中将价格存储为分(cent)非常有用，比如：

use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('price')
    ->summarize(Sum::make()->money('EUR', divideBy: 100))
use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('price')
    ->summarize(Sum::make()->money('EUR', divideBy: 100))

默认情况下，应用的本地化设置将用于格式化金额。如果你想自定义本地化设置，你可以将其传递给 locale 参数：

use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('price')
    ->summarize(Sum::make()->money('EUR', locale: 'nl'))
use Filament\Tables\Columns\Summarizers\Average;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('price')
    ->summarize(Sum::make()->money('EUR', locale: 'nl'))

此外，你可以在服务提供者的 boot() 方法中，使用 Table::$defaultNumberLocale 方法，用以设置整个应用的默认本地化设置：

use Filament\Tables\Table;
 
Table::$defaultNumberLocale = 'nl';
use Filament\Tables\Table;

Table::$defaultNumberLocale = 'nl';

限制文本长度

使用 limit()，你可以限制汇总值的长度：

use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;
 
TextColumn::make('sku')
    ->summarize(Range::make()->limit(5))
use Filament\Tables\Columns\Summarizers\Range;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('sku')
    ->summarize(Range::make()->limit(5))

添加前后缀

你可以将前后缀添加到汇总值：

use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Support\HtmlString;
 
TextColumn::make('volume')
    ->summarize(Sum::make()
        ->prefix('Total volume: ')
        ->suffix(new HtmlString(' m&sup3;'))
    )
use Filament\Tables\Columns\Summarizers\Sum;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Support\HtmlString;

TextColumn::make('volume')
    ->summarize(Sum::make()
        ->prefix('Total volume: ')
        ->suffix(new HtmlString(' m&sup3;'))
    )

自定义汇总

在 using() 方法中返回值，你可以创建自定义汇总：

use Filament\Tables\Columns\Summarizers\Summarizer;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Query\Builder;
 
TextColumn::make('name')
    ->summarize(Summarizer::make()
        ->label('First last name')
        ->using(fn (Builder $query): string => $query->min('last_name')))
use Filament\Tables\Columns\Summarizers\Summarizer;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Query\Builder;

TextColumn::make('name')
    ->summarize(Summarizer::make()
        ->label('First last name')
        ->using(fn (Builder $query): string => $query->min('last_name')))

回调可以访问数据库 $query 构建器实例，以执行计算。它应该返回展示在表格中的值。

条件性隐藏汇总

要隐藏汇总，你可以传递一个布尔值或者一个返回布尔值的函数给 hidden() 方法。如果需要，你可以通过函数的 $query 参数让该汇总器(summarizer)访问 Eloquent 查询的 Builder 实例：

use Filament\Tables\Columns\Summarizers\Summarizer;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;
 
TextColumn::make('sku')
    ->summarize(Summarizer::make()
        ->hidden(fn (Builder $query): bool => ! $query->exists()))
use Filament\Tables\Columns\Summarizers\Summarizer;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('sku')
    ->summarize(Summarizer::make()
        ->hidden(fn (Builder $query): bool => ! $query->exists()))

此外，你可以使用 visable() 方法来实现相反的效果：

use Filament\Tables\Columns\Summarizers\Summarizer;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;
 
TextColumn::make('sku')
    ->summarize(Summarizer::make()
        ->visible(fn (Builder $query): bool => $query->exists()))
use Filament\Tables\Columns\Summarizers\Summarizer;
use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('sku')
    ->summarize(Summarizer::make()
        ->visible(fn (Builder $query): bool => $query->exists()))

汇总行分组

你可以在分组中使用汇总，以在分组中显示记录汇总。如果你选择将汇总表添加到分组表中的列中，则此操作会自动生效。

隐藏分组的行并只显示汇总

使用 groupsOnly() 方法，你可以在分组内隐藏行，并且只显示每个分组的汇总。这对于许多报告场景很有用。

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();
}
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();
}

Edit on GitHub

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

#概述

#可用汇总器

#Average

#Count

#统计图标出现的次数

#Range

#日期范围

#文本范围

#在范围中包含 null 值

#Sum

#设置标签

#设置数据集范围

#格式化

#数字格式化

#货币格式化

#限制文本长度

#添加前后缀

#自定义汇总

#条件性隐藏汇总

#汇总行分组

#隐藏分组的行并只显示汇总

概述