表格基本使用

简单示例

Dcat\Admin\Grid类用于生成基于数据模型的表格，先来个例子，数据库中有movies表

  1. CREATE TABLE `movies` (
  2.   `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  3.   `title` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
  4.   `director` int(10) unsigned NOT NULL,
  5.   `describe` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
  6.   `rate` tinyint unsigned NOT NULL,
  7.   `released` enum(0, 1),
  8.   `release_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
  9.   `created_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
  10.   `updated_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
  11.   PRIMARY KEY (`id`)
  12. ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

对应的数据模型为App\Models\Movie，对应的数据仓库为App\Admin\Repositories\Movie，数据仓库代码如下：

{tip} 如果你的数据来自MySQL，则数据仓库不是必须的，你也可以直接使用Model。

  1. <?php
  3. namespace App\Admin\Repositories;
  5. use Dcat\Admin\Repositories\EloquentRepository;
  6. use App\Models\Movie as MovieModel;
  8. class Movie extends EloquentRepository
  9. {
  10.     protected $eloquentClass = MovieModel::class;
  12.     /**
  13.      * 设置表格查询的字段，默认查询所有字段
  14.      * 
  15.      * @return array
  16.      */
  17.     public function getGridColumns(){
  18.         return ['id', 'title', 'director', 'rate', ...];
  19.     }
  20. }

下面的代码可以生成表movies的数据表格：

  1. <?php
  3. namespace App\Admin\Controllers;
  5. use App\Admin\Repositories\Movie;
  6. use Dcat\Admin\Grid;
  7. use Dcat\Admin\Controllers\AdminController;
  9. class MovieController extends AdminController
  10. {
  11.     protected function grid()
  12.     {
  13.         return Grid::make(new Movie(), function (Grid $grid) {
  14.             // 第一列显示id字段，并将这一列设置为可排序列
  15.             $grid->column('id', 'ID')->sortable();
  17.             // 第二列显示title字段，由于title字段名和Grid对象的title方法冲突，所以用Grid的column()方法代替
  18.             $grid->column('title');
  20.             // 第三列显示director字段，通过display($callback)方法设置这一列的显示内容为users表中对应的用户名
  21.             $grid->column('director')->display(function($userId) {
  22.                 return User::find($userId)->name;
  23.             });
  25.             // 第四列显示为describe字段
  26.             $grid->column('describe');
  28.             // 第五列显示为rate字段
  29.             $grid->column('rate');
  31.             // 第六列显示released字段，通过display($callback)方法来格式化显示输出
  32.             $grid->column('released', '上映?')->display(function ($released) {
  33.                 return $released ? '是' : '否';
  34.             });
  36.             // 下面为三个时间字段的列显示
  37.             $grid->column('release_at');
  38.             $grid->column('created_at');
  39.             $grid->column('updated_at');
  41.             // filter($callback)方法用来设置表格的简单搜索框
  42.             $grid->filter(function ($filter) {
  43.                 // 设置created_at字段的范围查询
  44.                 $filter->between('created_at', 'Created Time')->datetime();
  45.             });
  46.         });
  47.     }
  48. }

表格显示模式

table_collapse

在这个版本开始，默认的表格布局将会采用 table_collapse 模式，效果如下

表格基本使用 - 图1 表格基本使用 - 图2

如果想要切换回旧版本的表格布局样式，可以在 app/Admin/bootstrap.php中加上

  1. Grid::resolving(function (Grid $grid) {
  2.     $grid->tableCollapse(false);
  3. });

边框模式

通过withBorder方式可以让表格显示边框

  1. $grid->withBorder();

效果 表格基本使用 - 图3

禁用边框模式

  1. $grid->withBorder(false);

基本使用方法

添加列 (column)

  1. // 添加单列
  2. $grid->column('username', '用户名');
  4. // 添加多列
  5. $grid->columns('email', 'username' ...);

修改来源数据

  1. $grid->model()->where('id', '>', 100);
  3. $grid->model()->orderBy('profile.age');
  5. // 回收站数据
  6. $grid->model()->onlyTrashed();
  8. ...

同时也可以使用以下方式

  1. protected function grid()
  2. {
  3.     return Grid::make(Model::with('...')->where(...), function (Grid $grid) {
  4.         ...
  5.     });
  6. }

其它查询方法可以参考eloquent的查询方法

修改显示输出 (display)

  1. $grid->column('text')->display(function($text) {
  2.     return str_limit($text, 30, '...');
  3. });
  5. // 允许混合使用多个“display”方法
  6. $grid->column('name')->display(function ($name) {
  7.      return "<b>$name</b>";
  8.  })->display(function ($name) {
  9.     return "<span class='label'>$name</span>";
  10. });
  12. $grid->column('email')->display(function ($email) {
  13.     return "mailto:$email";
  14. });
  16. // 可以直接写字符串
  17. $grid->column('username')->display('...');
  19. // 添加不存在的字段
  20. $grid->column('column_not_in_table')->display(function () {
  21.     return 'blablabla....'.$this->id;
  22. });

显示序号 (number)

通过number方法可以在表格中添加一列从1开始计算的行序号列

  1. $grid->number();

设置名称 (setName)

当页面存在多个Grid表格时，需要给表格设置不同的名称，否则部分功能可能会出现冲突的情况

  1. $grid->setName('name1');

获取当前行数据 (row)

display()方法接收的匿名函数绑定了当前行的数据对象，可以在里面调用当前行的其它字段数据

  1. $grid->column('first_name');
  2. $grid->column('last_name');
  4. // 不存的字段列
  5. $grid->column('full_name')->display(function () {
  6.     return $this->first_name.' '.$this->last_name;
  7. });

设置工具栏按钮样式

工具栏按钮默认显示outline模式，效果如下

用法

  1. $grid->toolsWithOutline();
  3. // 禁止
  4. $grid->toolsWithOutline(false);

效果 表格基本使用 - 图4

禁用outline后的效果

表格基本使用 - 图5

如果你希望某个按钮不使用outline模式，可以在按钮的class属性中加上disable-outline

  1. $grid->tools('<a class="btn btn-primary disable-outline">测试按钮</a>');

设置创建按钮

此功能默认开启

  1. // 禁用
  2. $grid->disableCreateButton();
  3. // 显示
  4. $grid->showCreateButton();

开启弹窗创建表单

此功能默认不开启

  1. $grid->enableDialogCreate();
  3. // 设置弹窗宽高，默认值为 '700px', '670px'
  4. $grid->setDialogFormDimensions('50%', '50%');

修改创建以及更新按钮的路由 (setResource)

设置修改创建以及更新按钮的路由前缀

  1. $grid->setResource('auth/users');

设置查询过滤器

此功能默认开启

  1. // 禁用
  2. $grid->disableFilter();
  3. // 显示
  4. $grid->showFilter();
  6. // 禁用过滤器按钮
  7. $grid->disableFilterButton();
  8. // 显示过滤器按钮
  9. $grid->showFilterButton();

行选择器 (rowSelector)

  1. // 禁用
  2. $grid->disableRowSelector();
  3. // 显示
  4. $grid->showRowSelector();

设置选择中行的标题字段

设置选中后需要显示的字段，如不设置，默认取 name、 title、 username中的一个。

  1. $grid->column('full_name');
  2. $grid->column('age');
  4. ...
  6. $grid->rowSelector()->titleColumn('full_name');

设置选择中行的ID字段

设置选中后需要保存的字段，默认为 数据表主键(id) 字段

  1. $grid->column('new_id');
  3. ...
  5. $grid->rowSelector()->idColumn('new_id');

设置checkbox选择框颜色

默认 primary，支持：default、 primary、 success、 info、 danger、 purple、 inverse。

  1. $grid->rowSelector()->style('success');

点击当前行任意位置选中

此功能默认不开启。

  1. $grid->rowSelector()->click();

设置选中行的背景颜色

  1. use Dcat\Admin\Admin;
  3. $grid->rowSelector()->background(Admin::color()->dark20());

设置默认选中 (check)

Since v2.0.21

通过check方法可以设置默认选中的行，此方法接受一个array类型或匿名函数参数

  1. // 设置默认选中第 1/3/5 行
  2. $grid->rowSelector()->check([0, 2, 4]);
  4. // 传递闭包
  5. $grid->rowSelector()->check(function () {
  6.     // 设置默认选中第 1/3/5 行
  7.     return in_array($this->_index, [0, 2, 4]);
  8. });
  10. // 在闭包中使用当前行其他字段
  11. $grid->rowSelector()->check(function () {
  12.     // 设置默认选中 id > 10 的行
  13.     return $this->id > 10;
  14. });

禁止更改选中状态 (disable)

Since v2.0.21

通过disable方法可以设置禁止更改选中状态的行，此方法接受一个array类型或匿名函数参数

  1. // 禁止第 1/3/5 行更改选中状态
  2. $grid->rowSelector()->disable([0, 2, 4]);
  4. // 传递闭包
  5. $grid->rowSelector()->disable(function () {
  6.     // 禁止第 1/3/5 行更改选中状态
  7.     return in_array($this->_index, [0, 2, 4]);
  8. });
  10. // 在闭包中使用当前行其他字段
  11. $grid->rowSelector()->disable(function () {
  12.     // 禁止 id > 10 的行更改选中状态
  13.     return $this->id > 10;
  14. });
  16. // disable 可以和 check 方法一起使用
  17. $grid->rowSelector()->check([2, 4])->disable([0, 2, 4]);

设置行操作按钮

  1. // 禁用
  2. $grid->disableActions();
  3. // 显示
  4. $grid->showActions();
  6. // 禁用详情按钮
  7. $grid->disableViewButton();
  8. // 显示详情按钮
  9. $grid->showViewButton();
  11. // 禁用编辑按钮
  12. $grid->disableEditButton();
  13. // 显示编辑按钮
  14. $grid->showEditButton();
  16. // 禁用快捷编辑按钮
  17. $grid->disableQuickEditButton();
  18. // 显示快捷编辑按钮
  19. $grid->showQuickEditButton();
  21. // 设置弹窗宽高，默认值为 '700px', '670px'
  22. $grid->setDialogFormDimensions('50%', '50%');
  25. // 禁用删除按钮
  26. $grid->disableDeleteButton();
  27. // 显示删除按钮
  28. $grid->showDeleteButton();

设置批量操作按钮 (batchActions)

  1. // 禁用
  2. $grid->disableBatchActions();
  3. // 显示
  4. $grid->showBatchActions();
  6. // 禁用批量删除按钮
  7. $grid->disableBatchDelete();
  8. // 显示批量删除按钮
  9. $grid->showBatchDelete();

设置工具栏 (toolbar)

  1. // 禁用
  2. $grid->disableToolbar();
  3. // 显示
  4. $grid->showToolbar();

设置刷新按钮 (refresh)

  1. // 禁用
  2. $grid->disableRefreshButton();
  3. // 显示
  4. $grid->showRefreshButton();

设置分页功能 (paginate)

  1. // 禁用
  2. $grid->disablePagination();
  3. // 显示
  4. $grid->showPagination();

简化分页 (simplePaginate)

启用 simplePaginate 功能后会使用Laravel的simplePaginate功能进行分页，当数据量较大时可以大幅提升页面的响应速度，但需要注意的是，使用此功能后将不会查询数据表的总行数。

  1. // 启用
  2. $grid->simplePaginate();
  4. // 禁用
  5. $grid->simplePaginate(false);

设置每页显示行数

  1. // 默认为每页20条
  2. $grid->paginate(15);

设置分页选择器选项

  1. $grid->perPages([10, 20, 30, 40, 50]);
  3. // 禁用分页选择器
  4. $grid->disablePerPages();

addTableClass

通过addTableClass可以给表格的table添加css样式

  1. $grid->addTableClass(['class1', 'class2']);

设置表格文字居中 (text-center)

  1. $grid->addTableClass(['table-text-center']);

显示横向滚动条 (scrollbarX)

显示表格横向滚动条，默认不显示

  1. // 启用
  2. $grid->scrollbarX();
  4. // 禁用
  5. $grid->scrollbarX(false);

设置表格外层容器

  1.  // 更改表格外层容器
  2. $grid->wrap(function (Renderable $view) {
  3.     $tab = Tab::make();
  5.     $tab->add('示例', $view);
  6.     $tab->add('代码', $this->code(), true);
  8.     return $tab;
  9. });

关联模型

参考表格关联关系