README

安装

您可以通过composer安装此包

composer require bernskioldmedia/laravel-livewire-widgets

在引入包之后，您应将基本样式导入到样式表中。您可以通过在您的 app.scss 文件中导入提供的 widgets.css 文件来完成此操作

@import "../../vendor/bernskioldmedia/laravel-livewire-widgets/resources/css/widgets.css";

/* Your styles */

提示： 您的导入应放在任何 Tailwind 导入之前，以确保正确应用样式。我们建议在加载Tailwind的基本、组件和实用工具时使用 @import 语法而不是 @tailwind。

安装包后，如果您计划使用图表小部件，请查看 Laravel Highcharts 包的安装说明。

发布配置和视图

通常不需要发布配置文件或视图。

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="laravel-livewire-widgets-config"

这是发布配置文件的内容

return [
    'livewire' => [
        'views' => [
            'chart-widget' => 'livewire-widgets::chart-widget',
            'statistic-widget' => 'livewire-widgets::statistic-widget',
        ],

        'skeletons' => [
            'base' => 'livewire-widgets::skeletons.widget',
            'chart-widget' => 'livewire-widgets::skeletons.chart-widget',
            'statistic-widget' => 'livewire-widgets::skeletons.statistic-widget',
        ],
    ],
];

可选地，您可以使用以下命令发布视图

php artisan vendor:publish --tag="laravel-livewire-widgets-views"

使用方法

支持的Widget类型

此包提供了两个有见地的Widget和一个您可以用来自定义的基Widget。

图表Widget。 使用我们的Laravel Highcharts包（捆绑）显示图表的小部件。
统计Widget。 显示带有标签、值和变化指示器的统计信息的小部件。

下面是如何使用这些小部件的说明。

创建Widget

要创建新的Widget，创建一个新的Livewire类，该类扩展了widget类型类之一，或者扩展了基本的 Widget 类。这些类的好位置是在 App\Livewire\Widgets 命名空间中。

注意： 如果您使用的是预定义的Widget之一（见上面列表），则不需要为您的Widget创建视图/blade文件。

懒加载

不幸的是，我们没有找到一种好的方法来实现默认的懒加载。因此，我们建议您向您的widget类添加 #[Lazy] 属性。

use BernskioldMedia\Laravel\Widgets\Widget;
use Livewire\Attributes\Lazy;

#[Lazy]
class MyWidget extends Widget
{
    //
}

渲染widget

要渲染widget，您可以使用 livewire Blade指令，就像使用其他Livewire组件一样

<livewire:my-widget />

图表Widget

图表Widget是显示图表的Widget。它们扩展了 ChartWidget 类。要使用此Widget，您必须首先设置 Laravel Highcharts 包。请参阅其文档以了解如何创建图表。

要创建图表Widget，扩展 ChartWidget 类并实现 getChart 方法。

use BernskioldMedia\Laravel\Widgets\ChartWidget;
use BernskioldMedia\LaravelHighcharts\Data\Chart;
use BernskioldMedia\LaravelHighcharts\Data\Series;

class MyChartWidget extends ChartWidget
{
    protected function getChart(): Chart
    {
        return Chart::create('line', 'highcharts')
            ->setTitle('My Chart')
            ->setSeries(Series::make([
                [1,2,3]
            ]));
    }
}

统计Widget

统计Widget是一个显示带有标签、值和变化指示器的统计信息的小部件。

要创建统计Widget，扩展 StatisticWidget 类并实现 getValue 方法。

use BernskioldMedia\Laravel\Widgets\StatisticWidget;

class MyStatisticWidget extends StatisticWidget
{
    protected function getValue(): int|float|null
    {
        return 123;
    }
}

要显示变化指示器，实现 ComparesValues 接口并从 getPreviousValue 方法返回上一个值。

use BernskioldMedia\Laravel\Widgets\StatisticWidget;
use BernskioldMedia\Laravel\Widgets\Contracts\ComparesValues;

class MyStatisticWidget extends StatisticWidget implements ComparesValues
{
    protected function getValue(): int|float|null
    {
        return 123;
    }
    
    protected function getPreviousValue(): int|float|null
    {
        return 100;
    }
}

您可以在widget上设置一些额外的属性

$showChange - 默认为true。是否显示变化指示器。
$changeAsPercentage - 默认为true。是否将变化显示为百分比（true）或绝对值（false）。
$invertedChange - 默认为 false。正变化是好的（true）还是坏的（false）。

小部件尺寸

小部件在响应式网格中渲染，可以渲染不同的宽度和高度。

所有宽度都在 WidgetWidths 枚举中可用，我们建议使用它而不是硬编码的字符串值。这些等于

1/4 - 25% 宽度
1/3 - 33% 宽度
1/2 - 50% 宽度
2/3 - 66% 宽度
3/4 - 75% 宽度
1/1 - 100% 宽度

高度基于小部件应占用的行数。因此，高度依赖于周围小部件的高度。所有高度都在 WidgetHeights 枚举中可用，我们建议使用它而不是硬编码的字符串。

以下高度可供使用

1 - 1 行
2 - 2 行
3 - 3 行
4 - 4 行

注意：行本身没有基本高度。

默认情况下，小部件以 1/4 宽度和 1 行高度渲染。您可以通过在您的部件上覆盖 width 和 height 属性来更改此设置。

class MyWidget extends Widget
{
    protected string $width = WidgetWidths::Half->value;
    protected string $height = WidgetHeights::One->value;
}

您还可以在您的视图中加载小部件时设置宽度和高度

<livewire:my-widget :width="WidgetWidths::Half->value" :height="WidgetHeights::One->value" />

添加标题

您可以通过在您的部件上实现 HasTitle 特性来添加对标题的支持。图表小部件和统计小部件都包括此特性。

此特性为您的部件添加了一个 title 属性。您可以在加载您的视图中的小部件时设置此属性，这提供了一种在加载时自定义标题的简单方法。您还可以通过从 defaultTitle 方法返回一个字符串来提供默认标题。

use BernskioldMedia\Laravel\Widgets\Concerns\HasTitle;

class MyWidget extends Widget
{
    use HasTitle;
    
    protected static function defaultTitle(): string
    {
        return 'My Widget';
    }
}

标题在您的视图中可用为 $widgetTitle。

添加描述

您可以通过在您的部件上实现 HasDescription 特性来添加对描述的支持。图表小部件和统计小部件都包括此特性。此特性为您的部件添加了一个 description 属性。您可以在加载您的视图中的小部件时设置此属性，这提供了一种在加载时自定义描述的简单方法。您还可以通过从 defaultDescription 方法返回一个字符串来提供默认描述。

use BernskioldMedia\Laravel\Widgets\Concerns\HasDescription;

class MyWidget extends Widget
{
    use HasDescription;
    
    protected static function defaultDescription(): string
    {
        return 'My Widget';
    }
}

描述在您的视图中可用为 $widgetDescription。

支持过滤器

您可以通过在您的部件上实现 Filterable 特性和 SupportsFilters 接口来添加对过滤器的支持。此特性为您的部件添加了一个 filters 属性。您可以在加载您的视图中的小部件时设置此属性，这提供了一种在加载时自定义过滤器的简单方法。

您还可以通过从 defaultFilters 方法返回一个数组来提供默认过滤器。

use BernskioldMedia\Laravel\Widgets\Concerns\Filterable;
use BernskioldMedia\Laravel\Widgets\Contracts\SupportsFilters;

class MyWidget extends Widget implements SupportsFilters
{
    use Filterable;
    
    protected static function defaultFilters(): array
    {
        return [
            'startDate' => today()->subDays(7),
            'endDate' => today(),
        ];
    }
}

默认过滤器将被您在加载小部件时传递的任何过滤器覆盖。

您还可以提供一组强制过滤器，这些过滤器在加载小部件时不能被用户覆盖。您可以通过覆盖 forcedFilters 方法来完成此操作。

use BernskioldMedia\Laravel\Widgets\Concerns\Filterable;
use BernskioldMedia\Laravel\Widgets\Contracts\SupportsFilters;

class MyWidget extends Widget implements SupportsFilters
{
    use Filterable;
    
    protected static function forcedFilters(): array
    {
        return [
            'startDate' => today()->subDays(7),
            'endDate' => today(),
        ];
    }
}

此特性还添加了与过滤器交互的便利方法

// Get all filters
$this->getFilters();

// Get a specific filter (or null if it doesn't exist)
$this->getFilter('startDate');

// Get a specific filter or return a custom value
$this->getFilter('startDate', today());

// Set a filter
$this->setFilter('startDate', today());

// Set multiple filters
$this->setFilters([
    'startDate' => today(),
    'endDate' => today()->addDays(7),
]);

// Check if a filter exists
$this->hasFilter('startDate');

// Remove a filter
$this->removeFilter('startDate');

// Clear all custom filters.
$this->resetFilters();

定义自定义视图

由于我们包含的辅助方法，添加视图的方式略有不同。您不是使用 render 方法，而是定义静态 view 方法并返回视图名称。

protected static function view(): string
{
    return 'widgets.my-widget';
}

您可以通过从 getViewData 方法返回一个数组来向视图传递额外的数据

protected static function getViewData(): array
{
    return [
        'myData' => 'Test',
    ];
}

占位符

该软件包为每种小部件类型以及一个基本的基小部件提供了默认占位符。要使用您自己的占位符视图，请从 placeholderView 方法返回视图名称

protected static function placeholderView(): string
{
    return 'widgets.skeletons.my-widget';
}

您可以通过从 placeholderData 方法返回一个数组，将数据传递给占位符视图。您应该将您的数据与父方法的数据合并。

protected static function getPlaceholderData(): array
{
    return array_merge(
        parent::getPlaceholderData(),
        [
            'title' => 'My Widget',
        ]
    );
}

自定义样式

我们已尽力使提供的样式尽可能无偏见，只为提供您最可能需要的结构，而不管外观如何。因此，您可能需要应用额外的自定义来使小部件类适合您的应用程序。

您可以使用以下 CSS 变量来自定义小部件网格间距和小部件填充：

:root {
    --ww-widgets-gap: 1.5rem;
    --ww-widget-padding: 1rem;
}

响应式小部件网格

默认情况下，小部件以响应式网格渲染。网格基于 CSS 网格，以略微有偏见的方式进行响应。这意味着每个小部件只配置了特定的宽度，这是它在桌面上的宽度。在小屏幕上，宽度会自动调整。

基本网格是：

默认情况下有 2 列
在 md 屏幕上（及以上）有 4 列
在 lg 屏幕上（及以上）有 12 列

每个小部件宽度对应于列数

1/4 - 1 列
1/3 - 1 列（基础），2 列（md），4 列（lg）
1/2 - 1 列（基础），2 列（md），6 列（lg）
2/3 - 2 列（基础），8 列（lg）
3/4 - 2 列（基础），3 列（md），9 列（lg）
1/1 - 2 列（基础），4 列（md），12 列（lg）

您可以通过在您自己的样式表中覆盖相应的宽度类来自定义此设置。

测试

composer test

bernskioldmedia / laravel-livewire-widgets

维护者

详细信息