列出记录

用标签页筛选记录

可在表格上方添加标签页，按预设条件筛选记录。每个标签页可以不同方式限定表格的 Eloquent 查询。要注册标签页，在列表页类上添加 getTabs() 方法，并返回 Tab 对象数组：

use Filament\Schemas\Components\Tabs\Tab;
use Illuminate\Database\Eloquent\Builder;

public function getTabs(): array
{
    return [
        'all' => Tab::make(),
        'active' => Tab::make()
            ->modifyQueryUsing(fn (Builder $query) => $query->where('active', true)),
        'inactive' => Tab::make()
            ->modifyQueryUsing(fn (Builder $query) => $query->where('active', false)),
    ];
}

自定义筛选标签页标签

数组的键会用作标签页标识符，以便持久化到 URL 查询字符串。每个标签页的标签也由键生成，但可通过向标签页的 make() 方法传入标签来覆盖：

use Filament\Schemas\Components\Tabs\Tab;
use Illuminate\Database\Eloquent\Builder;

public function getTabs(): array
{
    return [
        'all' => Tab::make('All customers'),
        'active' => Tab::make('Active customers')
            ->modifyQueryUsing(fn (Builder $query) => $query->where('active', true)),
        'inactive' => Tab::make('Inactive customers')
            ->modifyQueryUsing(fn (Builder $query) => $query->where('active', false)),
    ];
}

为筛选标签页添加图标

可通过向标签页的 icon() 方法传入 图标 为标签页添加图标：

use Filament\Schemas\Components\Tabs\Tab;

Tab::make()
    ->icon('heroicon-m-user-group')

也可使用 iconPosition() 方法，将图标位置改为标签之后而非之前：

use Filament\Support\Enums\IconPosition;

Tab::make()
    ->icon('heroicon-m-user-group')
    ->iconPosition(IconPosition::After)

为筛选标签页添加徽章

可通过向标签页的 badge() 方法传入字符串为标签页添加徽章：

use Filament\Schemas\Components\Tabs\Tab;

Tab::make()
    ->badge(Customer::query()->where('active', true)->count())

更改筛选标签页徽章颜色

可用 badgeColor() 方法更改徽章颜色：

use Filament\Schemas\Components\Tabs\Tab;

Tab::make()
    ->badge(Customer::query()->where('active', true)->count())
    ->badgeColor('success')

TIP

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

延迟加载筛选标签页徽章

若标签页徽章依赖昂贵查询（例如统计大数据集），初始页面加载可能变慢。可用 deferBadge() 延迟加载标签页徽章，在页面渲染后异步加载徽章值：

use Filament\Schemas\Components\Tabs\Tab;

Tab::make()
    ->badge(static fn (): int => Customer::query()->where('active', true)->count())
    ->deferBadge()

DANGER

使用 deferBadge() 时，badge() 的值必须由函数返回。若传入原始值如 badge(Customer::query()->count())，查询会在构建标签页时立即执行，使延迟失去意义。

徽章加载期间，每个延迟徽章位置会显示小型加载指示器。数据获取完成后，指示器会替换为实际徽章值。

为筛选标签页添加额外属性

也可使用 extraAttributes() 向筛选标签页传递额外 HTML 属性：

use Filament\Schemas\Components\Tabs\Tab;

Tab::make()
    ->extraAttributes(['data-cy' => 'statement-confirmed-tab'])

自定义默认标签页

要自定义页面加载时选中的默认标签页，可从 getDefaultActiveTab() 方法返回该标签页的数组键：

use Filament\Schemas\Components\Tabs\Tab;

public function getTabs(): array
{
    return [
        'all' => Tab::make(),
        'active' => Tab::make(),
        'inactive' => Tab::make(),
    ];
}

public function getDefaultActiveTab(): string | int | null
{
    return 'active';
}

解析记录时排除标签页查询

当用户与表格记录交互（例如点击操作按钮）时，Filament 会从数据库解析该记录。默认会应用当前标签页的查询，确保用户无法访问当前标签页范围之外的记录。

不过，当记录在用户于表格中看到之后状态发生变化时，你可能仍希望用户能与之交互。例如，若有「Active」标签页，而某个操作将记录设为 inactive，则同一模态中的后续操作将无法解析该记录。

可使用 excludeQueryWhenResolvingRecord() 方法，标记在解析记录时排除某标签页的查询：

use Filament\Schemas\Components\Tabs\Tab;
use Illuminate\Database\Eloquent\Builder;

public function getTabs(): array
{
    return [
        'active' => Tab::make()
            ->modifyQueryUsing(fn (Builder $query) => $query->where('active', true))
            ->excludeQueryWhenResolvingRecord(),
        'inactive' => Tab::make()
            ->modifyQueryUsing(fn (Builder $query) => $query->where('active', false))
            ->excludeQueryWhenResolvingRecord(),
    ];
}

DANGER

不要对强制授权规则的标签页使用 excludeQueryWhenResolvingRecord()。例如，若某标签页按租户或用户所有权限制记录，这些标签页应继续强制生效，以防止未授权访问。

授权

对于授权，Filament 会遵循应用中已注册的任意 模型策略。

若模型策略的 viewAny() 方法返回 true，用户即可访问列表页。

reorder() 方法用于控制 记录排序。

自定义表格 Eloquent 查询

尽管可以 自定义整个资源的 Eloquent 查询，也可仅为列表页表格做特定修改。为此，在资源的 table() 方法中使用 modifyQueryUsing()：

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

public static function table(Table $table): Table
{
    return $table
        ->modifyQueryUsing(fn (Builder $query) => $query->withoutGlobalScopes());
}

自定义页面内容

Filament 中每个页面都有自己的 schema，定义整体结构与内容。可通过定义 content() 方法覆盖页面 schema。列表页的 content() 默认包含以下组件：

use Filament\Schemas\Components\EmbeddedTable;
use Filament\Schemas\Components\RenderHook;
use Filament\Schemas\Schema;

public function content(Schema $schema): Schema
{
    return $schema
        ->components([
            $this->getTabsContentComponent(), // This method returns a component to display the tabs above a table
            RenderHook::make(PanelsRenderHook::RESOURCE_PAGES_LIST_RECORDS_TABLE_BEFORE),
            EmbeddedTable::make(), // This is the component that renders the table that is defined in this resource
            RenderHook::make(PanelsRenderHook::RESOURCE_PAGES_LIST_RECORDS_TABLE_AFTER),
        ]);
}

在 components() 数组中可插入任意 schema 组件。可通过调整数组顺序重排组件，或移除不需要的组件。

使用自定义 Blade 视图

若需进一步自定义，可将页面类上的静态 $view 属性覆盖为应用中的自定义视图：

protected string $view = 'filament.resources.users.pages.list-users';

这假定你已在 resources/views/filament/resources/users/pages/list-users.blade.php 创建了视图：

<x-filament-panels::page>
    {{ $this->content }} {{-- This will render the content of the page defined in the `content()` method, which can be removed if you want to start from scratch --}}
</x-filament-panels::page>