README

一个强大的Livewire数据表格包。非常适合需要数据表格解决方案的项目。

要查看完整演示，请访问Electric Grid Demo存储库。

特性

简单安装：使用简单的命令进行安装和包更新。
列：通过各种选项添加列到您的网格中，包括可排序、可样式化、可导出和可见。
过滤器：支持文本、数字、选择、多选、布尔值、时间选择器、日期选择器和日期时间选择器。
批量操作：提供在数据的多行上同时执行操作的能力。
表格导出：表格可以导出为xlsx、csv、pdf和html等格式。
搜索输入：您可以通过指定要搜索的列来启用搜索功能。
字母搜索：此功能允许您根据指定列中的特定字母搜索数据。
可切换列：隐藏或显示有用的列，以便专注于最相关的数据。
主题：使用不超过230行HTML的单个blade模板，使其非常容易进行主题化。
测试：提供运行测试的命令，以确保一切按预期工作。

安装

您可以通过composer安装此包

composer require tomshaw/electricgrid

运行安装命令。

php artisan electricgrid:install

运行更新命令以更新包

php artisan electricgrid:update

请确保将样式和脚本指令添加到您的布局中。

@vite(['resources/css/app.css', 'resources/js/app.js'])

@electricgridStyles
@electricgridScripts

将组件添加到您打算使用它的blade模板中。

这里命名空间是 App\Livewire\Tables，组件名称是 OrdersTable。

<livewire:tables.orders-table />

使用方法

构建方法。

使用builder方法填充您的表格。

构建方法必须返回一个Illuminate\Database\Eloquent\Builder实例。

use Illuminate\Database\Eloquent\Builder;
use TomShaw\ElectricGrid\Component;
use App\Models\Order;

class OrdersTable extends Component
{
    public array $computedColumns = ['posts_count'];
    
    public function builder(): Builder
    {
        return User::with(['roles', 'profile'])->withCount('posts');
    }
}

添加列。

使用列在网格中展示数据。

use TomShaw\ElectricGrid\{Component, Column};
use NumberFormatter;

class OrdersTable extends Component
{
    public function columns(): array
    {
        $numberFormat = new NumberFormatter('en_US', NumberFormatter::CURRENCY);

        return [
            Column::add('id', 'ID')
                ->sortable()
                ->stylable('text-center w-20')
                ->exportable(),

            Column::add('name', 'Customer')
                ->callback(function (Model $model) {
                    return view('livewire.tables.users-customer', ['model' => $model]);
                })
                ->searchable()
                ->sortable()
                ->exportable(),

            Column::add('status', 'Status')
                ->callback(function (Order $order) {
                    return OrderStatus::from($order->status)->name();
                })
                ->sortable()
                ->exportable(),

            Column::add('total', 'Total')
                ->callback(fn (Order $order) => $numberFormat->formatCurrency($order->total, 'USD'))
                ->searchable()
                ->sortable()
                ->exportable(),

            Column::add('invoiced', 'Invoiced')
                ->callback(fn (Order $order) => $order->invoiced ? 'Yes' : 'No')
                ->sortable()
                ->exportable(),

            Column::add('created_at', 'Created At')
                ->callback(fn (Order $order) => Carbon::parse($order->created_at)->format('F j, Y, g:i a'))
                ->sortable()
                ->exportable(),

            Column::add('updated_at', 'Updated At')
                ->callback(fn (Order $order) => Carbon::parse($order->updated_at)->format('F j, Y, g:i a'))
                ->sortable()
                ->exportable()
                ->visible(false),

        ];
    }
}

列过滤器。

过滤器允许您过滤网格中显示的数据。

可以使用addDataAttribute方法向过滤器添加数据属性。

use TomShaw\ElectricGrid\{Component, Column, Filter};
use App\Enums\OrderStatus;

class OrdersTable extends Component
{
    public function filters(): array
    {
        return [
            Filter::number('id')->placeholders('Min', 'Max'),
            Filter::text('name')->placeholder('Customer'),
            Filter::select('status')->options(OrderStatus::toOptions()),
            Filter::number('total')->placeholders('Min Total', 'Max Total'),
            Filter::boolean('invoiced')->labels('Yes', 'No'),
            Filter::datepicker('created_at')->addDataAttribute('format', 'H:i'),
            Filter::datetimepicker('updated_at'),
        ];
    }
}

Filter::number('id')

这为'id'字段创建了一个数字过滤器。

placeholders('Min', 'Max')：设置最小和最大输入字段的占位符文本。

Filter::text('name')

这为'名称'字段创建了一个文本过滤器。

placeholder('客户')：设置输入字段的占位符文本。

Filter::select('status')

这为'status'字段创建了一个选择过滤器。

options(OrderStatus::toOptions())：使用OrderStatus类的toOptions方法设置选择字段的选项。

Filter::number('total')

这为'total'字段创建了一个数字过滤器。

placeholders('Min Total', 'Max Total')：设置最小和最大输入字段的占位符文本。

Filter::boolean('invoiced')

这为'invoiced'字段创建了一个布尔过滤器。

labels('Yes', 'No')：设置true和false值的标签。

Filter::datepicker('created_at')

这为'created_at'字段创建了一个日期选择器过滤器。

addDataAttribute('format', 'H:i')：设置日期选择器的数据属性。在这种情况下，它用于设置日期格式。

Filter::datetimepicker('updated_at')

这为'updated_at'字段创建了一个日期时间选择器过滤器。日期时间选择器使用用户的本地日期和时间格式。

过滤器列类型

应使用适当的数据库列类型使用过滤器。

text：VARCHAR或TEXT
number：整数、浮点数、双精度浮点数或十进制
select：任何类型，只要值是一组选项
multiselect：任何类型，只要值是一组选项
boolean：TINYINT(1)，其中0为假，1为真
timepicker：时间
datepicker：日期
datetimepicker：日期时间

批量操作。

批量或批量操作允许同时执行对多行数据的操作。

您可以使用group和groupBy辅助方法将操作组合在一起。

use TomShaw\ElectricGrid\{Component, Column, Filter, Action};
use App\Enums\OrderStatus;

class OrdersTable extends Component
{
    public bool $showCheckbox = true;

    public function actions(): array
    {
        return [
            Action::make('approved', 'Mark Approved')
                ->group('Status Options')
                ->callback(fn ($status, $selected) => $this->updateStatusHandler($status, $selected)),

            Action::make('completed', 'Mark Completed')
                ->group('Status Options')
                ->callback(fn ($status, $selected) => $this->updateStatusHandler($status, $selected)),

            Action::make('cancelled', 'Mark Canceled')
                ->group('Status Options')
                ->callback(fn ($status, $selected) => $this->updateStatusHandler($status, $selected)),
        ];
    }

    public function updateStatusHandler(string $status, array $selectedItems)
    {
        $status = OrderStatus::fromName($status);

        foreach ($selectedItems as $index => $orderId) {
            event(new OrderStatusEvent($status->value, $orderId));
        }
    }
}

表格导出。

表格可以导出为以下格式：xlsx、csv、pdf、html。导出类型由基于扩展名的格式确定决定。如果您提供SalesOrders.xlsx的文件名，将生成Excel电子表格。

use TomShaw\ElectricGrid\{Component, Column, Filter, Action};
use App\Enums\OrderStatus;

class OrdersTable extends Component
{
    public bool $showCheckbox = true;

    public function actions(): array
    {
        return [
            Action::groupBy('Export Options', function () {
                return [
                    Action::make('csv', 'Export CSV')->export('SalesOrders.csv'),
                    Action::make('pdf', 'Export PDF')->export('SalesOrders.pdf'),
                    Action::make('html', 'Export HTML')->export('SalesOrders.html'),
                    Action::make('xlsx', 'Export XLSX')->export('SalesOrders.xlsx'),
                ];
            }),
        ];
    }
}

自定义Excel导出

Excel导出可以使用特定的样式和列宽进行自定义。

使用styles和columnWidths方法将自定义样式和列宽应用到Excel文件。

styles方法返回一个单元格样式的数组。数组的键是单元格引用，值是样式定义的数组。例如，'1' => ['font' => ['bold' => true]]将粗体字体样式应用到第1行中的所有单元格，而'B2' => ['font' => ['italic' => true]]将斜体字体样式应用到第2行的B列单元格。

columnWidths方法返回一个列宽的数组。数组的键是列字母，值是列的宽度。例如，'A' => 20将A列的宽度设置为20。

以下是如何为Excel导出定义自定义样式和列宽的示例

    public function actions(): array
    {
        return [
            Action::groupBy('Export Options', function () {
                return [
                    Action::make('xlsx', 'Export XLSX')
                        ->export('SalesOrders.xlsx')
                        ->styles($this->exportStyles)
                        ->columnWidths($this->exportWidths),
                ];
            }),
        ];
    }

    public function getExportStylesProperty()
    {
        return [
            '1'  => ['font' => ['bold' => true]],
            'B2' => ['font' => ['italic' => true]],
            'C'  => ['font' => ['size' => 16]],
        ];
    }

    public function getExportWidthsProperty()
    {
        return [
            'A' => 20,
            'B' => 30,
        ];
    }

搜索输入

通过添加以下属性并填充您希望搜索的列名来启用。

public array $searchTermColumns = ['title', 'description'];

字母搜索