README

这个包使得为 Laravel 应用创建数据网格变得容易，例如管理面板，或任何其他可搜索和可排序的列表。这个包提供了两种前端选项

Grid.js
DataGrid 的自有 Vue 3 前端。

两个前端都提供了服务器端功能，如搜索、排序和分页。

演示

请在此处找到演示应用程序这里以及演示应用程序的源代码这里;

安装

您可以通过 composer 安装此包

composer require wdev-rs/laravel-datagrid

可选 - 如果您使用 Grid.js，则使用 npm 安装此包

npm install gridjs@^6.0.0

通过运行以下命令发布供应商文件

使用 Grid.js 前端

php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="gridjs"

通过将以下行添加到您的 app.js 中注册 DataGrid 前端 Vue.js 组件

import DataGrid from "./vendor/laravel-datagrid/gridjs/Components/DataGrid.vue";

app.component('data-grid', DataGrid);

在视图文件（或另一个组件）中使用该组件

<data-grid
    base-url={{$baseUrl}}
    :columns="{{json_encode($columns)}}"
    :rows="{{json_encode($rows)}}"
></data-grid>

使用 Datagrid Vue 3 前端

php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="datagrid"

通过将以下行添加到您的 app.js 中注册 DataGrid 前端 Vue.js 组件

import DataGrid from "./vendor/laravel-datagrid/datagrid/Components/DataGrid.vue";

app.component('data-grid', DataGrid);

在视图文件（或另一个组件）中使用该组件

<data-grid
    :columns="{{json_encode($columns)}}"
    :rows="{{json_encode($rows)}}"
></data-grid>

用法

该包的基础是 \WdevRs\LaravelDatagrid\DataGrid\DataGrid 类。该类用于定义数据网格的列和行为。虽然您可以直接从控制器中使用此类，但我建议扩展它并为每个数据网格创建单独的类。

class CategoriesDataGrid extends DataGrid
{

    /**
     * CategoriesDataGrid constructor.
     */
    public function __construct()
    {
        $this->fromQuery(Category::query())
            ->column('id', 'ID', null, 50)
            ->column('name', 'Name', function ($category) {
                return view('admin.categories.actions.edit_link', ['category' => $category])->render();
            })
            ->key('id')
    }
}

使用 fromQuery 方法，您可以定义数据网格的基础查询。它接受 Laravel 查询构建器对象。使用 column 方法定义数据网格的列，参数如下

id - 数据库中字段的名称
name - 应在数据网格列标题中显示的标签
formatter - 可选，可调用函数允许您格式化列的显示。如上例所示，这可能是最优雅的方法之一，包括 blade 视图并渲染它。
width - 可选，列的宽度
sortable - 可选，布尔值，表示列是否可排序，默认为 true
searchable - 可选，布尔值，表示列是否可搜索，默认为 true

key 方法定义行的唯一标识符，通常是 id。指定 key 对于使用数据网格前端时的批量操作是必要的。

数据源

您可以从不同的数据源创建数据网格

Eloquent 查询 - 使用 fromQuery() 方法
集合 - 使用 fromCollection() 方法
数组 - 使用 fromArray() 方法

当数据网格定义就绪后，您可以将其添加到控制器中

    public function index(CategoriesDataGrid $dataGrid, Request $request)
    {
        return $dataGrid->render();
    }

如果未传递参数调用 render 方法，它将使用默认视图 resources/views/vendor/laravel-datagrid/datagrid.blade.php，或者您可以通过传递自己的视图并在其中使用数据网格来替换它

    public function index(CategoriesDataGrid $dataGrid, Request $request)
    {
        return $dataGrid->render('admin.common.index');
    }

如果您使用 Inertia 作为前端，则可以配置 laravel-datagrid 使用 Inertia 而不是 blade 进行渲染。首先发布配置文件

php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="config"

在发布的 config/laravel-datagrid.php 中更改渲染方法

'render_with' => \WdevRs\LaravelDatagrid\LaravelDatagrid::RENDER_INERTIA

现在您可以将 Vue 组件的名称传递给 render 方法，它将使用 Inertia 进行渲染。

可用命令

`php artisan make:datagrid <-M|--model> <-F|--fields>`

生成datagrid类，生成的类将放置在\App\DataGrids目录下

-M|--model 使用模型的名称
-F|--fields 字段名称，以逗号分隔：'field1,field2,field3' 或 'field1:label1,field2:label2,field3:label3'

生成的类

    class CategoriesDataGrid extends DataGrid
    {
    
        /**
         * CategoriesDataGrid constructor.
         */
        public function __construct()
        {
            $this->fromQuery(Category::query())
                ->column('id', 'ID', null, 50)
                ->column('name', 'Name')
        }
    }

使用示例

php artisan make datagrid command

前端定制

使用Grid.js

DataGrid的前端组件可以在resources/js/vendor/laravel-datagrid/gridjs/Components/DataGrid.vue找到。默认情况下，DataGrid包含一个行操作，即删除操作。这个操作可以在以下文件中找到：resources/js/vendor/laravel-datagrid/gridjs/actions/delete.js

您可以通过基于现有操作创建更多自定义操作来扩展它。要将操作添加到datagrid，扩展DataGrid.vue中的cols定义

            cols: this.columns.map((col) => {col.formatter = (cell) => html(cell); return col;}).concat(
                [{
                    name: 'Actions',
                    sort: false,
                    width: 50,
                    formatter: (cell, row) => {
                        return h('div', {className: "text-center"},
                            deleteAction.call(this, row.cells[0].data,row.cells[1].data),
                            yourCustomAction.call(this, row.cells[0].data,row.cells[1].data)
                        )
                    }
                }]
            )

使用Datagrid Vue3

与grid.js相比，Datagrid自己的vue 3前端提供了扩展功能，例如批量操作、筛选和行操作自定义。

批量操作

批量操作是运行多个记录上特定操作的方法。例如，一次性删除多个记录。

当使用批量操作时，建议在包装组件中使用datagrid。可以使用数组中的mass-actions属性定义批量操作：[{'action' : 'massDelete', 'label': 'Delete'}]

当用户选择行并运行操作时，datagrid将触发一个事件。事件的名称是您在action属性中定义的，在这种情况下为massDelete。按照常规方式处理事件，处理程序将获得selectedIds数组的参数

@massDelete="(selectedIds) => alert('Simulating mass delete on id(s): ' + selectedIds.join(','))"

请见下面的完整组件代码。

<script setup>
    import DataGrid from './../vendor/laravel-datagrid/datagrid/Components/DataGrid.vue'

    const props = defineProps({
        columns: Array,
        rows: Object,
    });

    const alert = (text) => {
        window.alert(text);
    }
</script>

<template>
    <data-grid
        :columns="props.columns"
        :rows="props.rows"
        :mass-actions="[{'action' : 'massDelete', 'label': 'Delete'}]"
        @massDelete="(selectedIds) => alert('Simulating mass delete on id(s): ' + selectedIds.join(','))"
    ></data-grid>
</template>

自定义行操作

默认情况下，DataGrid为所有行添加了2个行操作：编辑和删除。您可以使用actions插槽轻松自定义这些操作

    <data-grid
        :columns="props.columns"
        :rows="props.rows">

        <template #actions="{row, key}">
            <div class="flex flex-wrap justify-around">
                <a :href="'/'+row[key]+'/edit'"
                   class="font-medium text-blue-600 dark:text-blue-500 hover:underline mr-3">
                    <EditIcon class="fill-blue-600" :title="'Edit'"></EditIcon>
                </a>
                <a :href="'/'+row[key]+'/show'"
                   class="font-medium text-blue-600 dark:text-blue-500 hover:underline mr-3">
                    Show
                </a>
                <a :href="'/'+row[key]+'/export'"
                   class="font-medium text-blue-600 dark:text-blue-500 hover:underline mr-3">
                    Export
                </a>
            </div>
    </template>
</data-grid>

自定义搜索

如果您想制作一个更详细的搜索功能，而不是默认的搜索输入字段，请使用filters插槽。

    <data-grid
    :columns="dataColumns"
    :rows="dataRows"
>
    <template #filters>
        <form  class="p-3 mb-6 rounded bg-gray-50" @submit.prevent="filter">
            <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
                <div class="mx-1">
                    <InputLabel>Name</InputLabel>
                    <TextInput
                        id="name"
                        v-model="filters.name"
                        type="text"
                        class="block w-full mt-1"
                    />
                </div>
                <div class="mx-1">
                    <InputLabel>Code</InputLabel>
                    <TextInput
                        id="name"
                        v-model="filters.code"
                        type="text"
                        class="block w-full mt-1"
                    />
                </div>
            </div>
            <div class="mt-5 mb-2 ml-1 flex">
                <PrimaryButton>
                    Search
                </PrimaryButton>
                <SecondaryButton class="mx-3" @click="reset">
                    Reset
                </SecondaryButton>
            </div>
        </form>
    </template>
</data-grid>

在客户端添加自定义逻辑以收集数据和提交到搜索端点，例如使用ServerConfig类

    <script setup>
        import {ref} from "vue";
        import {ServerConfig} from "../vendor/laravel-datagrid/datagrid/ServerConfig";
        
        const dataColumns = ref(props.columns);
        const dataRows = ref(props.rows);
        
        const customFilteringEnabled = ref(false);
        
        const filters = ref({
        name: '',
        code: ''
        });
        
        const server = new ServerConfig();

        const filter = () => {
            const params = server.params();
            params.delete('search');
            params.delete('page');
            params.delete('limit');

            params.set('filters[name]', filters.value.name);
            params.set('filters[code]', filters.value.code)

            server.get(params).then((data) => {
                dataRows.value = data;
            });
        };

        const reset = () => {
            filters.value = {
                name: '',
                code: ''
            };

            const params = server.params();
            params.delete('filters[name]');
            params.delete('filters[code]');
            params.delete('page');
            params.delete('limit');

            server.get(params).then((data) => {
                dataRows.value = data;
            });
        }
    </script>

在服务器端覆盖基类DataGrid的search方法，以实现自定义筛选。

    public function search(?string $search): DataGrid
    {
        parent::search($search);

        $filters = collect(request()->get('filters'));

        $name = $filters->get('name');
        $code = $filters->get('code');

        $this->dataSource->query->when($name, fn ($query) => $query->where('name', 'like', '%'.$name.'%'));
        $this->dataSource->query->when($code, fn ($query) => $query->where('code', 'like', $code.'%'));

        return $this;
    }

请查看演示应用程序的源代码以获取有关如何在此处实现这些自定义的更多详细信息：Laravel DataGrid 演示

演示应用程序可以在这里找到。

从Laravel DataGrid 0.x升级

使用--force选项更新供应商资产

使用Grid.js

php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="gridjs" --force

使用datagrid前端

php artisan vendor:publish --provider="WdevRs\LaravelDatagrid\LaravelDatagridServiceProvider" --tag="datagrid" --force

在app.js中更新导入路径以使用正确的DataGrid组件（grid.js或datagrid），例如上面所示。

更新data-grid组件的使用，传递rows属性

<data-grid
    base-url={{$baseUrl}}
    :columns="{{json_encode($columns)}}"
    :rows="{{json_encode($rows)}}"
></data-grid>

测试

composer test

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件daniel@wdev.rs而不是使用问题跟踪器。

wdev-rs / laravel-datagrid

维护者

详细信息