Filament 中文文档

主题

全部文档

统计概览小部件 ​

简介 ​

Filament 自带「统计概览（stats overview）」小部件模板，可在单个小部件中展示多项统计，无需编写自定义视图。

先用命令创建小部件：

bash
php artisan make:filament-widget StatsOverview --stats-overview

该命令会创建新的 StatsOverview.php。打开后，在 getStats() 方法中返回 Stat 实例：

php
<?php

namespace App\Filament\Widgets;

use Filament\Widgets\StatsOverviewWidget as BaseWidget;
use Filament\Widgets\StatsOverviewWidget\Stat;

class StatsOverview extends BaseWidget
{
    protected function getStats(): array
    {
        return [
            Stat::make('Unique views', '192.1k'),
            Stat::make('Bounce rate', '21%'),
            Stat::make('Average time on page', '3:12'),
        ];
    }
}

然后在仪表盘中查看该小部件。

统计概览统计概览

为统计项添加描述与图标 ​

可添加 description() 提供补充信息，并配合 descriptionIcon()：

php
use Filament\Widgets\StatsOverviewWidget\Stat;

protected function getStats(): array
{
    return [
        Stat::make('Unique views', '192.1k')
            ->description('32k increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up'),
        Stat::make('Bounce rate', '21%')
            ->description('7% decrease')
            ->descriptionIcon('heroicon-m-arrow-trending-down'),
        Stat::make('Average time on page', '3:12')
            ->description('3% increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up'),
    ];
}

descriptionIcon() 还可接受第二个参数，把图标放在描述之前而非之后：

php
use Filament\Support\Enums\IconPosition;
use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Unique views', '192.1k')
    ->description('32k increase')
    ->descriptionIcon('heroicon-m-arrow-trending-up', IconPosition::Before)
带描述的统计概览带描述的统计概览

更改统计项颜色 ​

也可为统计项指定颜色：

php
use Filament\Widgets\StatsOverviewWidget\Stat;

protected function getStats(): array
{
    return [
        Stat::make('Unique views', '192.1k')
            ->description('32k increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up')
            ->color('success'),
        Stat::make('Bounce rate', '21%')
            ->description('7% increase')
            ->descriptionIcon('heroicon-m-arrow-trending-down')
            ->color('danger'),
        Stat::make('Average time on page', '3:12')
            ->description('3% increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up')
            ->color('success'),
    ];
}
带颜色的统计概览带颜色的统计概览

为统计项添加额外 HTML 属性 ​

也可用 extraAttributes() 向统计项传入额外 HTML 属性：

php
use Filament\Widgets\StatsOverviewWidget\Stat;

protected function getStats(): array
{
    return [
        Stat::make('Processed', '192.1k')
            ->color('success')
            ->extraAttributes([
                'class' => 'cursor-pointer',
                'wire:click' => "\$dispatch('setStatusFilter', { filter: 'processed' })",
            ]),
        // ...
    ];
}

本例中故意转义 $dispatch() 里的 $，因为需要直接传给 HTML，它不是 PHP 变量。

为统计项设置占位符 ​

有时统计值可能不可用——例如仪表盘在某段时期没有可展示内容。可用 placeholder() 定义值为空时应显示的内容：

php
use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Unique views', $uniqueViews)
    ->placeholder('-')

是否为空由 Laravel 的 blank() 辅助函数判定。例如 null 与空字符串为空，而 0 与 '0' 不为空。

全局设置默认占位符 ​

若希望应用中每个统计项默认回退到同一占位符，可在服务提供者的 boot() 方法中使用静态 configureUsing()：

php
use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::configureUsing(function (Stat $component): void {
    $component->placeholder('-');
});

单个统计项仍可通过自行调用 placeholder() 覆盖。

为统计项添加图表 ​

也可为每个统计项添加或链式调用 chart() 以提供历史数据。chart() 接受要绘制的数据点数组：

php
use Filament\Widgets\StatsOverviewWidget\Stat;

protected function getStats(): array
{
    return [
        Stat::make('Unique views', '192.1k')
            ->description('32k increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up')
            ->chart([7, 2, 10, 3, 15, 4, 17])
            ->color('success'),
        // ...
    ];
}
带图表的统计概览带图表的统计概览

在主题中为统计图表设置样式 ​

Chart.js 将统计项图表绘制在 <canvas> 上，因此样式表无法直接控制其线条。自定义主题仅为 CSS，故 Filament 将该线条形状暴露为 CSS 自定义属性，可在 .fi-wi-stats-overview-stat 或其上方任意元素上设置，以一次覆盖面板中全部统计项：

css
.fi-wi-stats-overview-stat {
    --stat-chart-border-width: 1;
    --stat-chart-line-tension: 0;
    --stat-chart-fill: none;
}

--stat-chart-border-width 加粗线条，--stat-chart-line-tension 控制弯曲（0 为直线段，最大到 1），--stat-chart-fill 填充其下方区域，可取 start、end、origin 或 stack，以及 none 表示不填充。

这些值交给 Chart.js 而非浏览器使用，因此是不带单位的纯数字与关键字。若设为 Chart.js 无法使用的值会被忽略并保留默认。配色方案变化时也会重新读取，故可为亮/暗模式设置不同值。

图表颜色取自统计项颜色。要在主题中更改，请用普通 color 声明为 .fi-wi-stats-overview-stat-chart-bg-color 与 .fi-wi-stats-overview-stat-chart-border-color 设置样式：

css
.fi-wi-stats-overview-stat {
    & .fi-wi-stats-overview-stat-chart-border-color {
        @apply text-gray-400 dark:text-gray-500;
    }
}

INFO

这些属性仅影响统计项内的图表。图表小部件使用各自以 --chart- 为前缀的属性集。

实时更新统计（轮询） ​

默认情况下，统计概览小部件每 5 秒刷新一次数据。

要自定义，可在类上覆盖 $pollingInterval 属性为新间隔：

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

也可完全禁用轮询：

php
protected ?string $pollingInterval = null;

禁用懒加载 ​

默认情况下，小部件会懒加载，即仅在页面上可见时才会加载。

要禁用此行为，可在小部件类上覆盖 $isLazy 属性：

php
protected static bool $isLazy = false;

添加标题与描述 ​

也可通过覆盖 $heading 与 $description 属性，在小部件上方添加标题与描述文本：

php
protected ?string $heading = 'Analytics';

protected ?string $description = 'An overview of some analytics.';

若需动态生成标题或描述，可改为覆盖 getHeading() 与 getDescription() 方法：

php
protected function getHeading(): ?string
{
    return 'Analytics';
}

protected function getDescription(): ?string
{
    return 'An overview of some analytics.';
}
带标题与描述的统计概览带标题与描述的统计概览