图表插件

#开始

Filament 自带诸多"图表"插件模板，可以用来显示实时的、可交互的图表。

创建图表插件命令:

php artisan make:filament-widget BlogPostsChart --chart
php artisan make:filament-widget BlogPostsChart --chart

有多种可用的图表类，此处示例使用的是 LineChartWidget。

getHeading() 方法用来返回图表的标题。

getData() 方法用于返回一个包含数据集和标签的数组。每个数据集都是一个标签化数组用来绘制图表的 point，标签为字符串。Filament 用来渲染图表的这种数据结构，与 Chart.js图表库是一致的。你可以借助 Chart.js 文档去了解 getData() 方法基于图表类型可能的返回值。

<?php
 
namespace App\Filament\Widgets;
 
use Filament\Widgets\LineChartWidget;
 
class BlogPostsChart extends LineChartWidget
{
    protected function getHeading(): string
    {
        return 'Blog posts';
    }
 
    protected function getData(): array
    {
        return [
            'datasets' => [
                [
                    'label' => 'Blog posts created',
                    'data' => [0, 10, 5, 2, 21, 32, 45, 74, 65, 45, 77, 89],
                ],
            ],
            'labels' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        ];
    }
}
<?php

namespace App\Filament\Widgets;

use Filament\Widgets\LineChartWidget;

class BlogPostsChart extends LineChartWidget
{
    protected function getHeading(): string
    {
        return 'Blog posts';
    }

    protected function getData(): array
    {
        return [
            'datasets' => [
                [
                    'label' => 'Blog posts created',
                    'data' => [0, 10, 5, 2, 21, 32, 45, 74, 65, 45, 77, 89],
                ],
            ],
            'labels' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        ];
    }
}

现在，你可以在仪表盘上查看插件了。

#可用图表类型

以下是你可以继承的图表插件类清单，以及他们对应的 Chart.js文档页面，从中你可以知晓 getData() 应该怎么返回哪些值。

• Filament\Widgets\BarChartWidget - Chart.js 文档
• Filament\Widgets\BubbleChartWidget - Chart.js 文档
• Filament\Widgets\DoughnutChartWidget - Chart.js 文档
• Filament\Widgets\LineChartWidget - Chart.js 文档
• Filament\Widgets\PieChartWidget - Chart.js 文档
• Filament\Widgets\PolarAreaChartWidget - Chart.js 文档
• Filament\Widgets\RadarChartWidget - Chart.js文档
• Filament\Widgets\ScatterChartWidget - Chart.js 文档

#从 Eloquent 模型中生成图表数据

要想从 Eloquent 模型中生成数据，Filament 推荐你安装 flowframe/laravel-trend 包。查看文档请到 Flowframe 网站。

以下是使用 laravel-trend 包生成图表数据的一个示例：

use Flowframe\Trend\Trend;
use Flowframe\Trend\TrendValue;
 
protected function getData(): array
{
    $data = Trend::model(BlogPost::class)
        ->between(
            start: now()->startOfYear(),
            end: now()->endOfYear(),
        )
        ->perMonth()
        ->count();
 
    return [
        'datasets' => [
            [
                'label' => 'Blog posts',
                'data' => $data->map(fn (TrendValue $value) => $value->aggregate),
            ],
        ],
        'labels' => $data->map(fn (TrendValue $value) => $value->date),
    ];
}
use Flowframe\Trend\Trend;
use Flowframe\Trend\TrendValue;

protected function getData(): array
{
    $data = Trend::model(BlogPost::class)
        ->between(
            start: now()->startOfYear(),
            end: now()->endOfYear(),
        )
        ->perMonth()
        ->count();

    return [
        'datasets' => [
            [
                'label' => 'Blog posts',
                'data' => $data->map(fn (TrendValue $value) => $value->aggregate),
            ],
        ],
        'labels' => $data->map(fn (TrendValue $value) => $value->date),
    ];
}

#图表数据过滤

你可以安装图表过滤器，用以调整图表上显示的数据。通常用来调整图表数据渲染的时间周期：

要设置过滤器的默认值，使用 $filter 属性：

public ?string $filter = 'today';
public ?string $filter = 'today';

然后，定义 getFilters() 方法，返回一个值和标签组成的数组给过滤器：

protected function getFilters(): ?array
{
    return [
        'today' => 'Today',
        'week' => 'Last week',
        'month' => 'Last month',
        'year' => 'This year',
    ];
}
protected function getFilters(): ?array
{
    return [
        'today' => 'Today',
        'week' => 'Last week',
        'month' => 'Last month',
        'year' => 'This year',
    ];
}

你可以在 getData() 方法内使用当前活跃的过滤值：

protected function getData(): array
{
    $activeFilter = $this->filter;
    
    // ...
}
protected function getData(): array
{
    $activeFilter = $this->filter;
    
    // ...
}

#实时更新(轮询)

图表插件默认每5秒钟刷新一次数据。

你可以通过重写类上的 $pollingInterval 属性自定义间隔时间:

protected static ?string $pollingInterval = '10s';
protected static ?string $pollingInterval = '10s';

或者，也可以完全禁用轮询：

protected static ?string $pollingInterval = null;
protected static ?string $pollingInterval = null;

#设置图表最大高度

使用 $maxHeight 属性，你可以在图表上设置一个最大高度，以避免其变得太大：

protected static ?string $maxHeight = '300px';
protected static ?string $maxHeight = '300px';

#设置图表配置项

你可以在图表类中指定 $options 属性，用以控制 Chart.js 库提供的多个配置项。比如，你想让 LineChartWidget 类关闭 legend。

protected static ?array $options = [
    'plugins' => [
        'legend' => [
            'display' => false,
        ],
    ],
];
protected static ?array $options = [
    'plugins' => [
        'legend' => [
            'display' => false,
        ],
    ],
];

Edit on GitHub

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