Widgets

概述

Filament 允许你在页面内展示 Widget，置于页头(header)之下或者页脚(footer)之上。

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

创建资源 Widget

开始创建一个资源 Widget：

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

此命令会创建两个文件 - 在 app/Filament/Resources/CustomerResource/Widgets 目录下创建一个 Widget 类，在 resources/views/filament/resources/customer-resource/widgets 目录下生成一个视图文件。

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

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

如果你想了解如何创建及自定义 Widget，请查看仪表盘文档部分。

在资源页中显示 Widget

要在资源页面中展示 Widget，在相应页面中使用 getHeaderWidgets() 或者 getFooterWidgets() 方法:

<?php

namespace App\Filament\Resources\CustomerResource\Pages;

use App\Filament\Resources\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\ProductResource\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

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

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

该属性数组映射到 Widget 类中的公共 Livewire 属性：

use Filament\Widgets\Widget;

class CustomerOverview extends Widget
{
    public string $status;

    // ...
}

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