README

灵感来源于: Laravel Livewire Tables

该软件包是为黑材料内部项目制作的，目前不是作为“即用即装”的软件包

一个动态、响应式的 Laravel Livewire 表格组件，具有搜索、排序、复选框和分页功能。

安装

确保您已 安装 Laravel Livewire。

通过 composer 安装此软件包

composer require matiere-noire/laravel-livewire-table

此软件包旨在与 Laravel 前端脚手架 一起良好工作。

如果您现在正在做脚手架，您需要将 Livewire 的 @livewireScripts 和 @livewireStyles blade 指令添加到您的 resources/views/layouts/app.blade.php 文件中

<!-- Styles -->
<link href="{{ asset('css/app.css') }}" rel="stylesheet">
@livewireStyles

...

<!-- Scripts -->
<script src="{{ asset('js/app.js') }}"></script>
@livewireScripts

制作表格组件

使用 make 命令

php artisan make:table UserTable --model=User

这将在 app/Http/Livewire 文件夹中创建您的新表格组件。

创建组件后，您可能想编辑 query 和 column 方法

class UserTable extends TableComponent
{
    public function query()
    {
        return User::query();
    }

    public function columns()
    {
        return [
            Column::make('ID')->searchable()->sortable(),
            Column::make('Created At')->searchable()->sortable(),
            Column::make('Updated At')->searchable()->sortable(),
        ];
    }
}

您不需要在您的表格组件中使用 render() 方法或担心组件视图，因为软件包会自动处理这些。

使用表格组件

您可以在视图中像使用任何其他 Livewire 组件一样使用表格组件

@livewire('user-table')

现在您只需要更新您的表格组件类！

发布文件

发布文件是可选的。

发布表格视图文件

php artisan vendor:publish --tag=table-views

发布配置文件

php artisan vendor:publish --tag=table-config

表格组件属性

$table_class

设置用于 <table> 的 CSS 类名。默认为 table-hover。

示例

public $table_class = 'table-hover table-striped';

或者，通过 .env 全局应用

TABLE_CLASS="table-hover table-striped"

$thead_class

设置用于 <thead> 的 CSS 类名。默认为 thead-light。

示例

public $thead_class = 'thead-dark';

或者，通过 .env 全局应用

TABLE_THEAD_CLASS="thead-dark"

$header_view

设置用于表格头部的自定义视图（显示在搜索旁边）。

示例

public $header_view = 'users.table-header';

提示：您在表格组件中引用的任何视图都可以使用 Livewire 操作、触发器等！

{{-- resources/views/users/table-header.blade.php --}}
<button class="btn btn-primary" wire:click="createUser">Create User</button>

$footer_view

设置用于表格尾部的自定义视图（显示在分页旁边）。

示例

public $footer_view = 'users.table-footer';

$checkbox

布尔值，表示表格是否应使用复选框。默认为 true。

示例

public $checkbox = false;

或者，通过 .env 全局应用

TABLE_CHECKBOX=false

$checkbox_side

表格放置复选框的侧面。接受 left 或 right。默认为 right。

示例

public $checkbox_side = 'left';

或者，通过 .env 全局应用

TABLE_CHECKBOX_SIDE="left"

$checkbox_attribute

设置用于 $checkbox_values 的属性名。默认为 id。建议保持为 id。

示例

public $checkbox_attribute = 'id';

$checkbox_values

包含已选中值的数组。例如，如果 $checkbox_attribute 设置为 id，则此将包含已选中模型的 id 数组。然后您可以使用这些 id 在组件中做任何您想做的事情。例如，在自定义的 $header_view 中使用 deleteChecked 按钮。

示例 deleteChecked 按钮

<button class="btn btn-danger" onclick="confirm('Are you sure?') || event.stopImmediatePropagation();" wire:click="deleteChecked">
    Delete Checked
</button>

示例 deleteChecked 方法

public function deleteChecked()
{
    Car::whereIn('id', $this->checkbox_values)->delete();
}

$sort_attribute

设置默认排序的属性。默认为 id。这也适用于计数和关系。

示例

public $sort_attribute = 'created_at';

计数示例（如果在 query() 方法中添加了 ->withCount('relations')）

public $sort_attribute = 'relations_count';

关系示例（如果在 query() 方法中添加了 ->with('relation')）

public $sort_attribute = 'relation.name';

注意点号表示法的使用。在声明列关系属性时也使用这种表示法。

$sort_direction

设置默认排序方向。接受 asc 或 desc。默认为 desc。

示例

public $sort_direction = 'asc';

$per_page

设置每页显示的结果数量。默认为 15。

示例

public $per_page = 25;

或者，通过 .env 全局应用

TABLE_PER_PAGE=25

表格组件方法

query()

此方法返回一个 Eloquent 模型查询，用于表格。

示例

public function query()
{
    return Car::with('brand')->withCount('accidents');
}

columns()

此方法返回一个用于表格的 Column 数组。

示例

public function columns()
{
    return [
        Column::make('ID')->searchable()->sortable(),
        Column::make('Brand Name', 'brand.name')->searchable()->sortable(),
        Column::make('Name')->searchable()->sortable(),
        Column::make('Color')->searchable()->sortable()->view('cars.table-color'),
        Column::make('Accidents', 'accidents_count')->sortable(),
        Column::make()->view('cars.table-actions'),
    ];
}

声明 Column 与声明 Laravel Nova 字段类似。有关更多信息，请跳转到列声明部分。

thClass($attribute)

此方法用于计算表格表头 <th> 的 CSS 类。

$attribute

列属性。

示例

public function thClass($attribute)
{
    if ($attribute == 'name') return 'font-italic';
    if ($attribute == 'accidents_count') return 'text-right';
    if ($attribute == 'brand.name') return 'font-weight-bold';

    return null;
}

trClass($model)

此方法用于计算表格行 <tr> 的 CSS 类。

$model

表格行的模型实例。

示例

public function trClass($model)
{
    if ($model->name == 'Silverado') return 'table-secondary';
    if ($model->accidents_count > 8) return 'table-danger';
    if ($model->brand->name == 'Ford') return 'table-primary';

    return null;
}

tdClass($attribute, $value)

此方法用于计算表格数据 <td> 的 CSS 类。

$attribute

列属性。

$value

列值。

示例

public function tdClass($attribute, $value)
{
    if ($attribute == 'name' && $value == 'Silverado') return 'table-secondary';
    if ($attribute == 'accidents_count' && $value < 2) return 'table-success';
    if ($attribute == 'brand.name' && $value == 'Ford') return 'table-primary';

    return null;
}

mount()

此方法设置初始表格属性。如果您需要覆盖它，请确保调用 $this->setTableProperties()。

示例

public function mount()
{
    $this->setTableProperties();
    
    // my custom code
}

render()

此方法渲染表格组件视图。如果您需要覆盖它，请确保 return $this->tableView()。

示例

public function render()
{
    // my custom code
    
    return $this->tableView();
}

表格列声明

使用 Column 类声明您的表格列。

public function columns()
{
    return [
        Column::make('ID')->searchable()->sortable(),
        Column::make('Created At')->searchable()->sortable(),
        Column::make('Updated At')->searchable()->sortable(),
    ];
}

make($heading = null, $attribute = null)

$heading

用于表格列的标题，例如 创建时间。对于只读列可以是 null。

$attribute

用于表格列值的属性。如果为 null，则使用 $heading 的蛇形表示。

您还可以使用点号表示法指定 _count 和关系属性。

对于计数，假设我在 query() 中添加了 withCount()

public function query()
{
    return Car::withCount('accidents');
}

现在我可以创建一个使用此计数的列，如下所示

Column::make('Accidents', 'accidents_count')->sortable(),

对于关系，假设我在 query() 中添加了 with()

public function query()
{
    return Car::with('brand');
}

现在我可以使用关系属性中的任何一个来创建列，如下所示

Column::make('Brand ID', 'brand.id')->searchable()->sortable(),
Column::make('Brand Name', 'brand.name')->searchable()->sortable(),

searchable()

设置列可搜索。

sortable()

设置列可排序。

sortUsing($callback)

允许使用自定义逻辑进行排序。您提供的 callable 将接收以下参数

• $models：当前的 Eloquent 查询（\Illuminate\Database\Eloquent\Builder）。您应该应用您的排序逻辑到这个查询中，并返回它。
• $sort_attribute：当前排序的列的名称。如果您使用了嵌套关系进行排序，它将被正确转换为 relationship_table.column_name 格式，以便查询被正确作用域。
• $sort_direction：请求的排序方向，可以是 asc 或 desc。

此外，您的回调将通过 Laravel 的容器传递，因此您可以在回调中注入任何需要的依赖项。请确保在上述参数之前列出您的依赖项。

示例

Column::make('Paint Color')->searchable()->sortable()->sortUsing(function ($models, $sort_attribute, $sort_direction) {
    return $models->orderByRaw('?->\'$.color_code\' ?', [$sort_attribute, $sort_direction]);
});

这将使用 JSON 值 color_code 对 paint_color 列进行排序。

SQL 注入警告：如果您使用 Eloquent 的任何 *Raw 方法，请务必使用绑定功能。

view($view)

为列设置一个自定义视图。

示例

Column::make('Paint Color')->searchable()->sortable()->view('cars.table-paint-color'),

注意列仍然是 searchable() 和 sortable() 的，因为 Car 模型包含一个 paint_color 属性！

如果你正在创建一个只读列（用于操作按钮等），只需不要让它可搜索或可排序。

Column::make()->view('cars.table-actions'),

自定义列视图会传入 $model 和 $column 对象，以及从表格组件传递的变量。

对于 Paint Color 示例，我们可以像这样使用模型中的 paint_color 属性

{{-- resources/views/cars/table-paint-color.blade.php --}}
<i class="fa fa-circle" style="color: {{ $model->paint_color }};"></i>

对于操作按钮的示例，我们可以像这样使用模型中的 id 属性

{{-- resources/views/cars/table-actions.blade.php --}}
<button class="btn btn-primary" wire:click="showCar({{ $model->id }})">Show</button>
<button class="btn btn-primary" wire:click="editCar({{ $model->id }})">Edit</button>

使用自定义视图为关系列？没问题

{{-- resources/views/cars/table-brand-name.blade.php --}}
{{ $model->brand->name }}