Widgets

#概述

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

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

#创建资源 Widget

开始创建一个资源 Widget：

php artisan make:filament-widget CustomerOverview --resource=CustomerResource
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,
    ];
}
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,
        ];
    }
}
<?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;
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;
 
    // ...
}
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;
    }
 
    // ...
}
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()),
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()),
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',
        ]),
    ];
}
protected function getHeaderWidgets(): array
{
    return [
        CustomerResource\Widgets\CustomerOverview::make([
            'status' => 'active',
        ]),
    ];
}

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

use Filament\Widgets\Widget;
 
class CustomerOverview extends Widget
{
    public string $status;
 
    // ...
}
use Filament\Widgets\Widget;

class CustomerOverview extends Widget
{
    public string $status;

    // ...
}

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

Edit on GitHub

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