在资源页中使用 Widget

简介

Filament 允许你在页眉(header)下方、页脚(footer)上方的页面内展示 Widget 小插件。

你可以使用现有的仪表盘 Widget，或者专门为资源创建一个 Widget。

创建资源 Widget

要创建资源 Widget，请运行如下命令：

php artisan make:filament-widget CustomerOverview --resource=CustomerResource

该命令将会生成两个文件 —— 一个 Widget 类位于 app/Filament/Resources/Customers/Widgets 目录，以及一个视图文件在 resources/views/filament/resources/customers/widgets 目录中。

你必须在资源的 getWidgets() 方法中注册这个新的 Widget：

use App\Filament\Resources\Customers\Widgets\CustomerOverview;

public static function getWidgets(): array
{
    return [
        CustomerOverview::class,
    ];
}

如果你想了解如何创建和自定义 Widget，请查阅仪表盘相关文档。

在资源页上展示 Widget

要在资源页中展示 Widget，请在页面中使用 getHeaderWidgets() 或 getFooterWidgets() 方法：

<?php

namespace App\Filament\Resources\Customers\Pages;

use App\Filament\Resources\Customers\CustomerResource;

class ListCustomers extends ListRecords
{
    public static string $resource = CustomerResource::class;

    protected function getHeaderWidgets(): array
    {
        return [
            CustomerResource\Widgets\CustomerOverview::class,
        ];
    }
}

getHeaderWidgets() 返回要展示在页面内容上方的 Widget 数组，而 getFooterWidgets() 则展示在下方。

如果你想自定义用于 Widget 的网格列数，请查阅相关页面文档。

在 Widget 中展示当前记录

如果你想在编辑页或查看页中使用 Widget，你可以通过在 Widget 类中定义 $record 来访问当前记录：

use Illuminate\Database\Eloquent\Model;

public ?Model $record = null;

在 Widget 中访问页面表格数据

如果你在列表页中使用 Widget，通过将 ExposesTableToWidgets trait 添加到页面类中，你可以访问表格数据。

use Filament\Pages\Concerns\ExposesTableToWidgets;
use Filament\Resources\Pages\ListRecords;

class ListProducts extends ListRecords
{
    use ExposesTableToWidgets;

    // ...
}

然后，在 Widget 类中，你需要添加 InteractsWithPageTable trait，并且在 getTablePage() 方法中返回页面类名称：

use App\Filament\Resources\Products\Pages\ListProducts;
use Filament\Widgets\Concerns\InteractsWithPageTable;
use Filament\Widgets\Widget;

class ProductStats extends Widget
{
    use InteractsWithPageTable;

    protected function getTablePage(): string
    {
        return ListProducts::class;
    }

    // ...
}

在该 Widget 类中，现在你可以使用 $this->getPageTableQuery() 方法，访问 Eloquent 查询构造器获取表格数据：

use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Total Products', $this->getPageTableQuery()->count()),

此外，使用 $this->getPageTableRecords() 方法，你可以在当前页面中访问记录集合。

use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Total Products', $this->getPageTableRecords()->count()),

在资源页中传递属性给 Widget

在资源页面中注册 Wiget 时，你可以使用 make() 方法传入一个 Livewire 属性数组：

protected function getHeaderWidgets(): array
{
    return [
        CustomerResource\Widgets\CustomerOverview::make([
            'status' => 'active',
        ]),
    ];
}

该属性数组映射到 Widget 类上的公共(public) Livewire 属性

use Filament\Widgets\Widget;

class CustomerOverview extends Widget
{
    public string $status;

    // ...
}

现在，你可以使用 $this->status 访问 Widget 类中的 $status。