bagisto-datagrid-development

DataGrid 开发

管理列表页由一个 DataGrid 子类和三行接线代码组成。 引擎（packages/Webkul/DataGrid）负责分页、搜索、筛选、排序、已保存筛选条件和导出；子类提供查询并描述列。代码库中共有 51 个 DataGrid，应复制最接近的实现，而不是另创一种写法。

四个方法

Webkul\DataGrid\DataGrid 声明了两个抽象方法和两个可选钩子：

方法	是否必需	用途
prepareQueryBuilder()	是	返回一个查询构建器，而不是集合
prepareColumns()	是	每列调用一次 addColumn([...])
prepareActions()	否	每行的操作，每项都必须经过 ACL 检查
prepareMassActions()	否	复选框操作，每项都必须经过 ACL 检查

仅在默认值不合适时才覆盖这些可调属性：$primaryColumn（默认为 'id'）、$sortColumn、$sortOrder（'desc'）、$itemsPerPage（10）、$perPageOptions。

写法

class CurrencyDataGrid extends DataGrid
{
    /**
     * Prepare query builder.
     *
     * @return Builder
     */
    public function prepareQueryBuilder()
    {
        return DB::table('currencies')
            ->select('id', 'name', 'code');
    }

    /**
     * Add Columns.
     *
     * @return void
     */
    public function prepareColumns()
    {
        $this->addColumn([
            'index'      => 'name',
            'label'      => trans('admin::app.settings.currencies.index.datagrid.name'),
            'type'       => 'string',
            'searchable' => true,
            'filterable' => true,
            'sortable'   => true,
        ]);
    }

    /**
     * Prepare actions.
     *
     * @return void
     */
    public function prepareActions()
    {
        if (bouncer()->hasPermission('settings.currencies.edit')) {
            $this->addAction([
                'index'  => 'edit',
                'icon'   => 'icon-edit',
                'title'  => trans('admin::app.settings.currencies.index.datagrid.edit'),
                'method' => 'GET',
                'url'    => fn ($row) => route('admin.settings.currencies.edit', $row->id),
            ]);
        }
    }
}

只有当正在编辑的文件原本就对齐时，才对齐 addColumn/addAction 数组中的 =>；Pint 不会强制要求对齐与否，而且代码库中两种写法都有。

接线

控制器在 AJAX 请求时返回 JSON，否则返回视图——同一路由，两种响应：

public function index()
{
    if (request()->ajax()) {
        return datagrid(CurrencyDataGrid::class)->process();
    }

    return view('admin::settings.currencies.index');
}

Blade 端只需一个指向同一路由的标签：

<x-admin::datagrid :src="route('admin.settings.currencies.index')" />

如果类没有继承 DataGrid，datagrid() 就会抛出 InvalidDataGridException，因此类名是唯一的约定。

参考文件

文件	适用场景
columns.md	列类型、搜索/筛选/排序标志、下拉选项、闭包、联接和 addFilter
actions.md	行操作、批量操作、ACL 检查、导出

不可妥协的要求

• prepareQueryBuilder() 必须返回构建器。 调用 ->get()、->paginate() 或映射为集合，都会破坏分页、筛选和导出，因为引擎会在你返回的查询上追加条件。
• 查询构建器是唯一应使用 DB:: 的地方。 在 Bagisto 的其他地方都应通过仓库操作；DataGrid 按设计基于查询构建器构建。
• 每个操作和批量操作都必须用 bouncer()->hasPermission(...) 包裹。 未做权限限制的操作会显示给无权执行该操作的管理员，而 DataGrid 是最容易遗漏这一点的地方。
• 每个 label 都必须通过 trans() 处理，并将键添加到全部 23 个语言区域中。
• 联接查询中的每个别名列都需要 addFilter()——参见 columns.md。否则，对该列进行筛选或排序会导致 SQL 列名不明确错误。
• 对闭包插值的内容进行转义。 单元格通过 v-html 渲染。引擎会先从原始值中移除标签，但不会移除引号，因此放入属性中的值可能会跳出属性范围。参见 columns.md。

必需子技能： 在认定任何更改完成之前，使用 bagisto-change-verification。