概述 - 表格 - Filament

简介

Column 类可以在 Filament\Tables\Columns 命名空间中找到。它们放置在 $table->columns() 方法中。Filament 内含多个内置列字段：

可编辑的列字段允许用户在不离开当前表格的情况下，更新数据库中的数据：

你也可以创建自定义列字段，以你期望的方式展示数据。

列使用静态 make() 方法创建，传入其唯一名称。通常，列名对应于 Eloquent 模型的属性名。你也可以使用“点语法”访问关联中的属性：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')

TextColumn::make('author.name')

字段内容 (state)

Column 旨在提供一种简单易用、优化展示 Eloquent 记录数据的方式。尽管如此，它很灵活，你可以展示任何来源的数据，不只是 Eloquent 记录中的属性。

列字段展示的数据称为“状态”。当使用面板资源时，表格知悉它要展示的记录。也就是说，列的状态是基于记录的属性值设置的。比如，如果列用在 PostResource 的表格中，那么当前贴文(post)的 title 属性值将会被显示。

use Filament\Tables\Components\TextColumn;

TextColumn::make('title')

如果你想访问存储在关联中的值，你可以使用“点语法”。首先是你要访问数据的关联名，随后紧跟着点号，然后是属性名：

use Filament\Tables\Components\TextColumn;

TextColumn::make('author.name')

你也可以使用“点语法”访问 Eloquent 模型中的 JSON/数组字段的值。首先是属性名，紧随着点号，最后是你想要读取的 JSON 对象的键名：

use Filament\Tables\Components\TextColumn;

TextColumn::make('meta.title')

设置列的状态值

使用 state() 方法，你可以传递自定义状态到列中：

use Filament\Tables\Components\TextColumn;

TextColumn::make('title')
    ->state('Hello, world!')

state() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

设置列的默认状态

当列为空(其状态为 null)时，你可以使用 default() 方法定义要使用的替代状态。此方法将默认状态视为真实状态，因此图片或颜色等列将显示默认图像或颜色。

use Filament\Tables\Components\TextColumn;

TextColumn::make('title')
    ->default('Untitled')

当列为空时添加占位符文本

有时，你可能希望为状态为空的列显示占位符文本，该列的样式为浅灰色文本。这与默认值不同，因为占位符始终是文本，而不会被视为真实状态。

use Filament\Tables\Components\TextColumn;

TextColumn::make('title')
    ->placeholder('Untitled')

Column with a placeholder for empty state

展示关联数据

你可以使用“点语法”访问关联中的列。首先是关联名，其后紧跟着点号，最后是要展示的列名：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('author.name')

关联计数

如果你希望计算列中关联记录的数量，你可以使用 counts() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('users_count')->counts('users')

本例中，users 是要计数的关联名。列名必须是 users_count，因为这是 Laravel 用来存储计数结果的命名规范。

如果你想在计算前设置关联的查询范围，你可以传入一个数组到该方法中，其中键是关联名，值为设置 Eloquent 查询范围的函数：

use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('users_count')->counts([
    'users' => fn (Builder $query) => $query->where('is_active', true),
])

确定关联是否存在

如果你想说明列中的关联记录是否存在，你可以使用 exist() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('users_exists')->exists('users')

本例中，users 是要检查是否存在的关联名。列名必须是 users_exists，因为这是 Laravel 用来存储计数结果的命名规范。

如果你想在计算前设置关联的查询范围，你可以传入一个数组到该方法中，其中键是关联名，值为设置 Eloquent 查询范围的函数：

use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('users_exists')->exists([
    'users' => fn (Builder $query) => $query->where('is_active', true),
])

聚合关联

Filament 提供多种方法用于聚合关联字段，包括 avg()、max()、min() 和 sum()。比如，如果你想显示列中所有关联的平均值，你可以使用 avg() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('users_avg_age')->avg('users', 'age')

上例中，users 是关联名，而 age 是要计算平均值的字段。列名必须是 users_avg_age，因为这是 Laravel 用来存储聚合结果的命名规范。

如果你想在计算前设置关联的查询范围，你可以传入一个数组到该方法中，其中键是关联名，值为设置 Eloquent 查询范围的函数：

use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('users_avg_age')->avg([
    'users' => fn (Builder $query) => $query->where('is_active', true),
], 'age')

设置列标签

默认情况下，列标签(显示在表格的标题栏中)是由列名生成的。你可以使用 label() 方法自定义：

use Filament\Tables\Components\TextColumn;

TextColumn::make('name')
    ->label('Full name')

除了允许静态值之外，label() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

如果你希望使用本地化字符串翻译，以此方式自定义标签非常有用：

use Filament\Tables\Components\TextColumn;

TextColumn::make('name')
    ->label(__('columns.name'))

排序

列可以通过点击列标签进行排序。要让列可排序，你必须使用 sortable() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->sortable()

Filament 会使用列名将 orderBy() 子句应用到 Eloquent 查询。这对于列名与数据库字段名相匹配的简单情况非常有用。它还可以处理关系。

然而，许多列并非如此简单。列的状态可能是自定义的，或者使用 Eloquent 访问器。在这种情况下，你可能需要自定义排序行为。

你可以传递一个包含实际数据库字段的数组，用于对表中的列进行排序：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('full_name')
    ->sortable(['first_name', 'last_name'])

本例中，full_name 不是字符串的真实字段，而 first_name 和 last_name 列是真实字段。而当以 full_name 字段排序时，Filament 将以 first_name 和 last_name 排序。这里为什么传入两个字段是因为，当两个字段的 first_name 相同时，将使用 last_name 进行排序。如果你的用例没有这样的要求，你可以按照需要只传入一个字段。

你也可以直接与 Eloquent 查询进行交互，以自定义应用到该列的排序方式：

use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('full_name')
    ->sortable(query: function (Builder $query, string $direction): Builder {
        return $query
            ->orderBy('last_name', $direction)
            ->orderBy('first_name', $direction);
    })

query 参数的函数可以注入各种 utility 作为参数。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Direction	`string`	`$direction`	The direction that the column is currently being sorted on, either `'asc'` or `'desc'`.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent query builder	`Illuminate\Database\Eloquent\Builder`	`$query`	The query builder to modify.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

默认排序

如果没有应用其他排序，你可以选择默认对表进行排序。你可以使用 defaultSort() 方法：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->defaultSort('stock', direction: 'desc');
}

第二个参数是可选的，默认为 'asc'。

如果你传入表格名作为第一个参数，Filament 将使用该行的排序行为(自定义排序列或查询函数)。不过，如果你需要按照不存在于表格或数据库中的列来进行排序，你应该传入一个查询函数：

use Filament\Tables\Table;
use Illuminate\Database\Eloquent\Builder;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->defaultSort(query: function (Builder $query): Builder {
            return $query->orderBy('stock');
        });
}

在用户 Session 中持久化排序

要在用户 Session 中持久化排序，请使用 persistSortInSession() 方法：

use Filament\Tables\Table;

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

设置默认排序选项标签

使用 defaultSortOptionLabel() 方法，可以设置默认排序选项标签：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->defaultSortOptionLabel('Date');
}

搜索

在表格的右上角使用文本输入字段，列可以是可搜索的。要使之可搜索，你必须使用 searchable() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->searchable()

默认情况下，Filament 会将一个 where 子句应用到 Eloquent 查询，用以搜索该列名。当列名匹配数据库字敦名时，这非常有用。它也可以处理关联。

不过，许多字段并不那么简单。列的状态值可能是自定义的，或者使用了 Eloquent 访问器。这种情况下，你可能需要自定义搜索行为。

你可以在表格中传入一个真实的数据库字段数组，用以搜索对应的列：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('full_name')
    ->searchable(['first_name', 'last_name'])

本例中，full_name 字段不是数据库的真实字段，但是 first_name 和 last_name 是真实的。当搜索 full_name 字段时，Filament 会通过 first_name 和 last_name 字段搜索表格。

你也可以直接和 Eloquent 查询交互，用以自定义列该如何应用到搜索：

use Filament\Tables\Columns\TextColumn;
use Illuminate\Database\Eloquent\Builder;

TextColumn::make('full_name')
    ->searchable(query: function (Builder $query, string $search): Builder {
        return $query
            ->where('first_name', 'like', "%{$search}%")
            ->orWhere('last_name', 'like', "%{$search}%");
    })

query 参数的函数可以注入各种 utility 作为参数。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent query builder	`Illuminate\Database\Eloquent\Builder`	`$query`	The query builder to modify.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
Search	`string`	`$search`	The current search input value.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

添加其他可搜索列到表格中

通过传递列名数组到 searchable() 方法，你可以允许搜索其他未在表格中展示的列：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->searchable(['id']);
}

你可以使用点语法在关联中进行搜索：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->searchable(['id', 'author.id']);
}

你也可以传入自定义函数用以搜索：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->searchable([
            'id',
            'author.id',
            function (Builder $query, string $search): Builder {
                if (! is_numeric($search)) {
                    return $query;
                }
            
                return $query->whereYear('published_at', $search);
            },
        ]);
}

自定义表格搜索字段占位符

在 $table 上使用 searchPlaceholder() 方法，你可以自定义搜索字段的占位符：

use Filament\Tables\Table;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->searchPlaceholder('Search (ID, Name)');
}

单列搜索

使用 isIndividual 参数，你可以启用每列搜索字段：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->searchable(isIndividual: true)

Table with individually searchable column

如果你使用了 isIndividual 参数，你仍然可以使用用于整个表格的“全局”搜索输入字段来搜索该列。

要禁用此功能，同时保留单独搜索功能，你需要使用 isGlobal 参数：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->searchable(isIndividual: true, isGlobal: false)

自定义表格搜索防抖

你可以在 $table 上使用 searchDebounce() 方法，自定义所有表格搜索字段的防抖动时间。默认值为 500ms：

use Filament\Tables\Table;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->searchDebounce('750ms');
}

在输入框失焦时搜索

你可以使用 searchOnBlur() 方法更改行为，使表格仅在用户输入失去焦点(制表符或点击失焦)时进行搜索，而不是在用户键入搜索时自动重新加载表内容(这会受到搜索字段的防抖动(debounce)的影响)：：

use Filament\Tables\Table;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->searchOnBlur();
}

在用户 Session 中持久化搜索

要在用户 Session 中持久化表格或者单独列的搜索，请使用 persistSearchInSession 或者 persistColumnSearchInSession 方法：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->persistSearchInSession()
        ->persistColumnSearchesInSession();
}

禁用搜索词拆分

默认情况下，表格搜索会将搜索词拆分为单个单词，并分别搜索每个单词。这允许更灵活的搜索查询。然而，当涉及大数据集时，它可能会对性能产生负面影响。你可以使用表上的 splitSearchTerms(false) 方法禁用此行为：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->splitSearchTerms(false);
}

可点击的单元格内容

当点击单元格时，你可以打开一个网址或者触发一个 Action。

打开 URL

要打开 URL，你可以使用 url() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->url(fn (Post $record): string => route('posts.edit', ['post' => $record]))

url() 方法也可以接受函数来动态计算其值，你可以将各种 utility 作为参数注入函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

TIP

你可以也选择一个 URL 使之用以整行，而不只是单个列。请查看记录 URL 相关文档。

当同时使用记录 URL 和列 URL 时，列 URL 将仅覆盖这些单元格的记录 URL。

你也可以选择在新的标签页中打开 URL：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->url(fn (Post $record): string => route('posts.edit', ['post' => $record]))
    ->openUrlInNewTab()

触发操作

要在点击单元格时运行函数，你可以使用 action() 方法。每个方法接受一个 $record 参数，你可以使用它来自定义 Action 的行为：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->action(function (Post $record): void {
        $this->dispatch('open-post-edit-modal', post: $record->getKey());
    })

Action 模态框

传递 Action 对象到 action() 方法中，你可以打开 Action 模态框：

use Filament\Actions\Action;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->action(
        Action::make('select')
            ->requiresConfirmation()
            ->action(function (Post $record): void {
                $this->dispatch('select-post', post: $record->getKey());
            }),
    )

传入到 action() 方法的 Action 对象必须使用唯一的名称，以避免与该表格的其他 Action 混淆。

阻止单元格被点击

使用 disabledClick() 方法，你可以阻止单元格被点击：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->disabledClick()

如果启用了行 URL，该单元格将无法点击。

你可以指定一个 tootip 使之在鼠标移入单元格时展示：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->tooltip('Title')

除了允许静态值之外，tooltip() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

对齐列内容

水平对齐列内容

使用 alignStart()、alignCenter() 或者 alignEnd()方法，你可以将列内容对齐到起始位置(左到右界面的左边，右到左界面的右边)、中间或者结尾处(左到右界面的右边，右到左界面的左边)：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->alignStart() // This is the default alignment.

TextColumn::make('email')
    ->alignCenter()

TextColumn::make('email')
    ->alignEnd()

此外，你也可以传递 Alignment 枚举到 alignment() 方法：

use Filament\Support\Enums\Alignment;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->label('Email address')
    ->alignment(Alignment::End)

除了允许静态值之外，alignment() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

垂直对齐列内容

使用 verticallyAlignStart()、verticallyAlignCenter() 或者 verticallyAlignEnd() 方法，你可以将列内容对齐到开始、中间或者结尾：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->verticallyAlignStart()

TextColumn::make('name')
    ->verticallyAlignCenter() // This is the default alignment.

TextColumn::make('name')
    ->verticallyAlignEnd()

此外，你也可以传递 VerticalAlignment 枚举到 verticalAlignment() 方法中：

use Filament\Support\Enums\VerticalAlignment;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->verticalAlignment(VerticalAlignment::Start)

除了允许静态值之外，verticalAlignment() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

Table with column vertically aligned to the start

允许列标题换行

默认情况下，如果列标题需要占用更多空间，它不会换行。你可以使用 wrapHeader() 方法，允许其换行：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->wrapHeader()

当然，你也可以传入一个布尔值用以控制标题是否可换行：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->wrapHeader(FeatureFlag::active())

wrapHeader() 方法也可以接受函数来动态计算其值，你可以将各种 utility 作为参数注入函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

控制列的宽度

默认情况下，列将会占据根据需要尽可能多的空间。使用 grow() 方法，你可以允许某些列占用比其他列更多的空间：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->grow()

此外，你也可以定义列的宽度，它将会使用 style 属性传递给标题单元格，所以你可以使用任何有效的 CSS 值：

use Filament\Tables\Columns\IconColumn;

IconColumn::make('is_paid')
    ->label('Paid')
    ->boolean()
    ->width('1%')

width() 方法也可以接受函数来动态计算其值，你可以将各种 utility 作为参数注入函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

列分组

使用 ColumnGroup 对象，你可以将多个列分组到同一个标题下面：

use Filament\Tables\Columns\ColumnGroup;
use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\TextColumn;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            TextColumn::make('title'),
            TextColumn::make('slug'),
            ColumnGroup::make('Visibility', [
                TextColumn::make('status'),
                IconColumn::make('is_featured'),
            ]),
            TextColumn::make('author.name'),
        ]);
}

第一个参数是分组的标签，而第二个参数是该分组下的列对象数组：

你也可以在 ColumnGroup 对象上控制分组标题对齐和换行。你可以在该对象上使用链式调用 columns() 而非将其作为第二个参数传入，提升多字段的 Fluency。

use Filament\Support\Enums\Alignment;
use Filament\Tables\Columns\ColumnGroup;

ColumnGroup::make('Website visibility')
    ->columns([
        // ...
    ])
    ->alignCenter()
    ->wrapHeader()

隐藏列

使用 hidden() 或者 visible() 方法，你可以隐藏列：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->hidden()

TextColumn::make('email')
    ->visible()

要条件性地隐藏列，你可以传入一个布尔值到这些方法中：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('role')
    ->hidden(FeatureFlag::active())

TextColumn::make('role')
    ->visible(FeatureFlag::active())

允许用户管理列

切换列的可见性

用户可以自己隐藏或者显示表格列。要让列变成可切换的，请使用 toggleable() 方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->toggleable()

默认隐藏可切换列

默认情况下，可切换的列是可见的。要隐藏这些类：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('id')
    ->toggleable(isToggledHiddenByDefault: true)

列重新排序

使用 reorderableColumns() 方法，你可以允许列在表格中重新排序：

use Filament\Tables\Table;

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

实时列管理

默认情况下，列管理器的更改(切换和重新排序列)会延迟，并且不会影响表，直到用户单击“Apply(应用)”按钮。要禁用此功能并使过滤器“实时”更新，请使用 deferColumnManager(false)方法：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->reorderableColumns()
        ->deferColumnManager(false);
}

自定义列管理器下拉触发操作

要自定义列管理器下拉触发按钮，你可以使用 columnManagerTriggerAction() 并传入一个返回 Action 的闭包。所有自定义触发按钮可用的方法在此处都可以使用：

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

public function table(Table $table): Table
{
    return $table
        ->filters([
            // ...
        ])
        ->columnManagerTriggerAction(
            fn (Action $action) => $action
                ->button()
                ->label('Column Manager'),
        );
}

添加其他 HTML 属性到列内容

你可以使用 extraAttributes() 方法，将额外的 HTML 属性传递给列内容，这些属性将会合并到其外层 HTML 元素中。属性应该以数组的形式显示，其键为属性名，值为属性值：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('slug')
    ->extraAttributes(['class' => 'slug-column'])

除了允许静态值之外，extraAttributes() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

By def默认情况下，多次调用 extraAttributes() 将会覆盖之前的属性。如果你想要换成合并属性，你可以传入 merge:true 到该方法中。

添加其他 HTML 属性到单元格

你也可以将其他 HTML 属性传递给围绕列内容的表格单元格：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('slug')
    ->extraCellAttributes(['class' => 'slug-cell'])

除了允许静态值之外，extraCellAttributes() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

默认情况下，多次调用 extraCellAttributes() 将会覆盖之前的属性。如果你想要换成合并属性，你可以传入 merge:true 到该方法中。

添加其他属性到标题单元格

你可以传递其他的 HTML 属性到围绕列内容表格标题单元格：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('slug')
    ->extraHeaderAttributes(['class' => 'slug-header-cell'])

除了允许静态值之外，extraHeaderAttributes() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Column	`Filament\Tables\Columns\Column`	`$column`	The current column instance.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current table row.
Row loop	`stdClass`	`$rowLoop`	The row loop object for the current table row.
State	`mixed`	`$state`	The current value of the column, based on the current table row.
Table	`Filament\Tables\Table`	`$table`	The current table instance.

默认情况下，多次调用 extraHeaderAttributes() 将会覆盖之前的属性。如果你想要换成合并属性，你可以传入 merge:true 到该方法中。

列 utility 注入

用于配置列的绝大多数方法都接受函数作为参数，而不是硬编码值：

use App\Models\User;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->placeholder(fn (User $record): string => "No email for {$record->name}")

TextColumn::make('role')
    ->hidden(fn (User $record): bool => $record->role === 'admin')

TextColumn::make('name')
    ->extraAttributes(fn (User $record): array => ['class' => "{$record->getKey()}-name-column"])

仅此便解锁了多个自定义的可能性。

此包也可以注入各种 utility 使之在这些函数中作为参数使用。所有接受函数作为参数的函数都可以注入 utility。

这些注入的 utility 需要使用指定的参数名。否则，Filament 无从知晓注入的是什么。

注入当前列状态

如果你想访问该类的当前值(状态)，请定义 $state 参数：

function ($state) {
    // ...
}

注入当前 Eloquent 记录

使用 $record 参数，你可以检索当前 Schema 的 Eloquent 记录：

use Illuminate\Database\Eloquent\Model;

function (?Model $record) {
    // ...
}

注入行 loop

要访问当前表格行的行 loop 对象，请定义 $rowLoop 参数：

function (stdClass $rowLoop) {
    // ...
}

注入当前 Livewire 组件实例

如果你想要访问当前 Livewire 组件实例，请定义 $livewire 参数：

use Livewire\Component;

function (Component $livewire) {
    // ...
}

注入当前列实例

如果你想要访问当前组件实例，请定义 $component 参数：

use Filament\Tables\Columns\Column;

function (Column $component) {
    // ...
}

注入当前表格实例

如果你想要访问当前表格实例，请定义 $table 参数：

use Filament\Tables\Table;

function (Table $table) {
    // ...
}

注入多个实例

参数使用反射动态注入，因此，你可以以任何顺序组合多个参数：

use App\Models\User;
use Livewire\Component as Livewire;

function (Livewire $livewire, mixed $state, User $record) {
    // ...
}

注入来自 Laravel 容器的依赖

你可以像平常一样注入来自于 Laravel 容器的东西，与其他 utility 一起注入：

use App\Models\User;
use Illuminate\Http\Request;

function (Request $request, User $record) {
    // ...
}

全局设置

如果你想要全局修改所有列的默认行为，你可以在服务提供者的 boot() 方法中调用其静态 configureUsing() 方法，用以传入一个闭包修改该字段使用的默认行为。比如，如果你想让所有 TextColumn() 列可切换，你可以使用 toogleable():

use Filament\Tables\Columns\TextColumn;

TextColumn::configureUsing(function (TextColumn $column): void {
    $column->toggleable();
});

当然，你仍然可以在每个列上覆盖该方法：

use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->toggleable(false)

Edit on GitHub

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

#简介

#字段内容 (state)

#设置列的状态值

#设置列的默认状态

#当列为空时添加占位符文本

#展示关联数据

#关联计数

#确定关联是否存在

#聚合关联

#设置列标签

#排序

#默认排序

#在用户 Session 中持久化排序

#设置默认排序选项标签

#搜索

#添加其他可搜索列到表格中

#自定义表格搜索字段占位符

#单列搜索

#自定义表格搜索防抖

#在输入框失焦时搜索

#在用户 Session 中持久化搜索

#禁用搜索词拆分

#可点击的单元格内容

#打开 URL

#触发操作

#Action 模态框

#阻止单元格被点击

#添加 tooltip 到列中

#对齐列内容

#水平对齐列内容

#垂直对齐列内容

#允许列标题换行

#控制列的宽度

#列分组

#隐藏列

#允许用户管理列

#切换列的可见性

#默认隐藏可切换列

#列重新排序

#实时列管理

#自定义列管理器下拉触发操作

#添加其他 HTML 属性到列内容

#添加其他 HTML 属性到单元格

#添加其他属性到标题单元格

#列 utility 注入

#注入当前列状态

#注入当前 Eloquent 记录

#注入行 loop

#注入当前 Livewire 组件实例

#注入当前列实例

#注入当前表格实例

#注入多个实例

#注入来自 Laravel 容器的依赖

#全局设置

简介

字段内容 (state)

设置列的状态值

设置列的默认状态

当列为空时添加占位符文本

展示关联数据

关联计数

确定关联是否存在

聚合关联

设置列标签

排序

默认排序

在用户 Session 中持久化排序

设置默认排序选项标签

搜索

添加其他可搜索列到表格中

自定义表格搜索字段占位符

单列搜索

自定义表格搜索防抖

在输入框失焦时搜索

在用户 Session 中持久化搜索

禁用搜索词拆分

可点击的单元格内容

打开 URL

触发操作

Action 模态框

阻止单元格被点击

添加 tooltip 到列中

对齐列内容

水平对齐列内容

垂直对齐列内容

允许列标题换行

控制列的宽度

列分组

隐藏列

允许用户管理列

切换列的可见性

默认隐藏可切换列

列重新排序

实时列管理

自定义列管理器下拉触发操作

添加其他 HTML 属性到列内容

添加其他 HTML 属性到单元格

添加其他属性到标题单元格

列 utility 注入

注入当前列状态

注入当前 Eloquent 记录

注入行 loop

注入当前 Livewire 组件实例

注入当前列实例

注入当前表格实例

注入多个实例

注入来自 Laravel 容器的依赖

全局设置