表格基本使用
<h1>表格基本使用</h1>
<h2>简单示例</h2>
<p><code>Dcat\Admin\Grid</code>类用于生成基于数据模型的表格，先来个例子，数据库中有<code>movies</code>表</p>
<pre><code class="language-sql">CREATE TABLE `movies` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`title` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
`director` int(10) unsigned NOT NULL,
`describe` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
`rate` tinyint unsigned NOT NULL,
`released` enum(0, 1),
`release_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
`created_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
`updated_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
</code></pre>
<p>对应的数据模型为<code>App\Models\Movie</code>，对应的数据仓库为<code>App\Admin\Repositories\Movie</code>，数据仓库代码如下：</p>
<p>> {tip} 如果你的数据来自<code>MySQL</code>，则<code>数据仓库</code>不是必须的，你也可以直接使用<code>Model</code>。</p>
<pre><code class="language-php">&lt;?php
namespace App\Admin\Repositories;
use Dcat\Admin\Repositories\EloquentRepository;
use App\Models\Movie as MovieModel;
class Movie extends EloquentRepository
{
protected $eloquentClass = MovieModel::class;
/**
* 设置表格查询的字段，默认查询所有字段
*
* @return array
*/
public function getGridColumns(){
return ['id', 'title', 'director', 'rate', ...];
}
}</code></pre>
<p>下面的代码可以生成表<code>movies</code>的数据表格：</p>
<pre><code class="language-php">&lt;?php
namespace App\Admin\Controllers;
use App\Admin\Repositories\Movie;
use Dcat\Admin\Grid;
use Dcat\Admin\Controllers\AdminController;
class MovieController extends AdminController
{
protected function grid()
{
return Grid::make(new Movie(), function (Grid $grid) {
// 第一列显示id字段，并将这一列设置为可排序列
$grid-&gt;column('id', 'ID')-&gt;sortable();
// 第二列显示title字段，由于title字段名和Grid对象的title方法冲突，所以用Grid的column()方法代替
$grid-&gt;column('title');
// 第三列显示director字段，通过display($callback)方法设置这一列的显示内容为users表中对应的用户名
$grid-&gt;column('director')-&gt;display(function($userId) {
return User::find($userId)-&gt;name;
});
// 第四列显示为describe字段
$grid-&gt;column('describe');
// 第五列显示为rate字段
$grid-&gt;column('rate');
// 第六列显示released字段，通过display($callback)方法来格式化显示输出
$grid-&gt;column('released', '上映?')-&gt;display(function ($released) {
return $released ? '是' : '否';
});
// 下面为三个时间字段的列显示
$grid-&gt;column('release_at');
$grid-&gt;column('created_at');
$grid-&gt;column('updated_at');
// filter($callback)方法用来设置表格的简单搜索框
$grid-&gt;filter(function ($filter) {
// 设置created_at字段的范围查询
$filter-&gt;between('created_at', 'Created Time')-&gt;datetime();
});
});
}
}</code></pre>
<h2>表格显示模式</h2>
<h3>table_collapse</h3>
<p>在这个版本开始，默认的表格布局将会采用 <code>table_collapse</code> 模式，效果如下</p>
<p><a href="<a href="https://cdn.learnku.com/uploads/images/202007/24/38389/4bCfBdtvq5.png!large"">https://cdn.learnku.com/uploads/images/202007/24/38389/4bCfBdtvq5.png!large"</a>; target="_blank">
<img class="img" src="<a href="https://cdn.learnku.com/uploads/images/202007/24/38389/4bCfBdtvq5.png!large"">https://cdn.learnku.com/uploads/images/202007/24/38389/4bCfBdtvq5.png!large"</a>; />
</a>
<a href="<a href="https://cdn.learnku.com/uploads/images/202007/24/38389/35KJXfVXib.png!large"">https://cdn.learnku.com/uploads/images/202007/24/38389/35KJXfVXib.png!large"</a>; target="_blank">
<img class="img" src="<a href="https://cdn.learnku.com/uploads/images/202007/24/38389/35KJXfVXib.png!large"">https://cdn.learnku.com/uploads/images/202007/24/38389/35KJXfVXib.png!large"</a>; />
</a> </p>
<p>如果想要切换回旧版本的表格布局样式，可以在 <code>app/Admin/bootstrap.php</code>中加上</p>
<pre><code class="language-php">Grid::resolving(function (Grid $grid) {
$grid-&gt;tableCollapse(false);
});</code></pre>
<h3>边框模式</h3>
<p>通过<code>withBorder</code>方式可以让表格显示边框</p>
<pre><code class="language-php">$grid-&gt;withBorder();</code></pre>
<p>效果
<img src="https://cdn.learnku.com/uploads/images/202004/26/38389/lKTZe0jwGg.png!large" alt="" /></p>
<p>禁用边框模式</p>
<pre><code class="language-php">$grid-&gt;withBorder(false);</code></pre>
<h2>基本使用方法</h2>
<h3>添加列 (column)</h3>
<pre><code class="language-php">// 添加单列
$grid-&gt;column('username', '用户名');
// 添加多列
$grid-&gt;columns('email', 'username' ...);</code></pre>
<h3>修改来源数据</h3>
<pre><code class="language-php">$grid-&gt;model()-&gt;where('id', '&gt;', 100);
$grid-&gt;model()-&gt;orderBy('profile.age');
// 回收站数据
$grid-&gt;model()-&gt;onlyTrashed();
...</code></pre>
<p>同时也可以使用以下方式</p>
<pre><code class="language-php">protected function grid()
{
return Grid::make(Model::with('...')-&gt;where(...), function (Grid $grid) {
...
});
}</code></pre>
<p>其它查询方法可以参考<code>eloquent</code>的查询方法</p>
<h3>修改显示输出 (display)</h3>
<pre><code class="language-php">$grid-&gt;column('text')-&gt;display(function($text) {
return str_limit($text, 30, '...');
});
// 允许混合使用多个“display”方法
$grid-&gt;column('name')-&gt;display(function ($name) {
return &quot;&lt;b&gt;$name&lt;/b&gt;&quot;;
})-&gt;display(function ($name) {
return &quot;&lt;span class='label'&gt;$name&lt;/span&gt;&quot;;
});
$grid-&gt;column('email')-&gt;display(function ($email) {
return &quot;mailto:$email&quot;;
});
// 可以直接写字符串
$grid-&gt;column('username')-&gt;display('...');
// 添加不存在的字段
$grid-&gt;column('column_not_in_table')-&gt;display(function () {
return 'blablabla....'.$this-&gt;id;
});</code></pre>
<h3>显示序号 (number)</h3>
<p>通过<code>number</code>方法可以在表格中添加一列从<code>1</code>开始计算的行序号列</p>
<pre><code class="language-php">$grid-&gt;number();</code></pre>
<h3>设置名称 (setName)</h3>
<p>当页面存在多个<code>Grid</code>表格时，需要给表格设置不同的名称，否则部分功能可能会出现冲突的情况</p>
<pre><code class="language-php">$grid-&gt;setName('name1');</code></pre>
<h3>获取当前行数据 (row)</h3>
<p><code>display()</code>方法接收的匿名函数绑定了当前行的数据对象，可以在里面调用当前行的其它字段数据</p>
<pre><code class="language-php">$grid-&gt;column('first_name');
$grid-&gt;column('last_name');
// 不存的字段列
$grid-&gt;column('full_name')-&gt;display(function () {
return $this-&gt;first_name.' '.$this-&gt;last_name;
});</code></pre>
<p><a name="outline"></a></p>
<h3>设置工具栏按钮样式</h3>
<p>工具栏按钮默认显示<code>outline</code>模式，效果如下</p>
<p>用法</p>
<pre><code class="language-php">$grid-&gt;toolsWithOutline();
// 禁止
$grid-&gt;toolsWithOutline(false);</code></pre>
<p>效果
<img src="https://cdn.learnku.com/uploads/images/202005/23/38389/hKWC1crYHw.png!large" alt="" /></p>
<p>禁用<code>outline</code>后的效果</p>
<p><img src="https://cdn.learnku.com/uploads/images/202005/23/38389/aaMdymSxoY.png!large" alt="" /></p>
<p>如果你希望某个按钮不使用<code>outline</code>模式，可以在按钮的<code>class</code>属性中加上<code>disable-outline</code></p>
<pre><code class="language-php">$grid-&gt;tools('&lt;a class=&quot;btn btn-primary disable-outline&quot;&gt;测试按钮&lt;/a&gt;');</code></pre>
<h3>设置创建按钮</h3>
<p>此功能默认开启</p>
<pre><code class="language-php">// 禁用
$grid-&gt;disableCreateButton();
// 显示
$grid-&gt;showCreateButton();</code></pre>
<h4>开启弹窗创建表单</h4>
<p>此功能默认不开启</p>
<pre><code class="language-php">$grid-&gt;enableDialogCreate();
// 设置弹窗宽高，默认值为 '700px', '670px'
$grid-&gt;setDialogFormDimensions('50%', '50%');</code></pre>
<h3>修改创建以及更新按钮的路由 (setResource)</h3>
<p>设置修改创建以及更新按钮的路由前缀</p>
<pre><code class="language-php">$grid-&gt;setResource('auth/users');</code></pre>
<h3>设置查询过滤器</h3>
<p>此功能默认开启</p>
<pre><code class="language-php">// 禁用
$grid-&gt;disableFilter();
// 显示
$grid-&gt;showFilter();
// 禁用过滤器按钮
$grid-&gt;disableFilterButton();
// 显示过滤器按钮
$grid-&gt;showFilterButton();</code></pre>
<h3>行选择器 (rowSelector)</h3>
<pre><code class="language-php">// 禁用
$grid-&gt;disableRowSelector();
// 显示
$grid-&gt;showRowSelector();</code></pre>
<h4>设置选择中行的标题字段</h4>
<p>设置选中后需要显示的字段，如不设置，默认取 <code>name</code>、 <code>title</code>、 <code>username</code>中的一个。</p>
<pre><code class="language-php">$grid-&gt;column('full_name');
$grid-&gt;column('age');
...
$grid-&gt;rowSelector()-&gt;titleColumn('full_name');</code></pre>
<h4>设置选择中行的ID字段</h4>
<p>设置选中后需要保存的字段，默认为 数据表主键(id) 字段</p>
<pre><code class="language-php">$grid-&gt;column('new_id');
...
$grid-&gt;rowSelector()-&gt;idColumn('new_id');</code></pre>
<h4>设置checkbox选择框颜色</h4>
<p>默认 <code>primary</code>，支持：<code>default</code>、 <code>primary</code>、 <code>success</code>、 <code>info</code>、 <code>danger</code>、 <code>purple</code>、 <code>inverse</code>。</p>
<pre><code class="language-php">$grid-&gt;rowSelector()-&gt;style('success');</code></pre>
<h4>点击当前行任意位置选中</h4>
<p>此功能默认不开启。</p>
<pre><code class="language-php">$grid-&gt;rowSelector()-&gt;click();</code></pre>
<h4>设置选中行的背景颜色</h4>
<pre><code class="language-php">use Dcat\Admin\Admin;
$grid-&gt;rowSelector()-&gt;background(Admin::color()-&gt;dark20());</code></pre>
<h4>设置默认选中 (check)</h4>
<p>> Since <code>v2.0.21</code></p>
<p>通过<code>check</code>方法可以设置默认选中的行，此方法接受一个<code>array</code>类型或<code>匿名函数</code>参数</p>
<pre><code class="language-php">// 设置默认选中第 1/3/5 行
$grid-&gt;rowSelector()-&gt;check([0, 2, 4]);
// 传递闭包
$grid-&gt;rowSelector()-&gt;check(function () {
// 设置默认选中第 1/3/5 行
return in_array($this-&gt;_index, [0, 2, 4]);
});
// 在闭包中使用当前行其他字段
$grid-&gt;rowSelector()-&gt;check(function () {
// 设置默认选中 id &gt; 10 的行
return $this-&gt;id &gt; 10;
});</code></pre>
<h4>禁止更改选中状态 (disable)</h4>
<p>> Since <code>v2.0.21</code></p>
<p>通过<code>disable</code>方法可以设置禁止更改选中状态的行，此方法接受一个<code>array</code>类型或<code>匿名函数</code>参数</p>
<pre><code class="language-php">// 禁止第 1/3/5 行更改选中状态
$grid-&gt;rowSelector()-&gt;disable([0, 2, 4]);
// 传递闭包
$grid-&gt;rowSelector()-&gt;disable(function () {
// 禁止第 1/3/5 行更改选中状态
return in_array($this-&gt;_index, [0, 2, 4]);
});
// 在闭包中使用当前行其他字段
$grid-&gt;rowSelector()-&gt;disable(function () {
// 禁止 id &gt; 10 的行更改选中状态
return $this-&gt;id &gt; 10;
});
// disable 可以和 check 方法一起使用
$grid-&gt;rowSelector()-&gt;check([2, 4])-&gt;disable([0, 2, 4]);</code></pre>
<h3>设置行操作按钮</h3>
<pre><code class="language-php">// 禁用
$grid-&gt;disableActions();
// 显示
$grid-&gt;showActions();
// 禁用详情按钮
$grid-&gt;disableViewButton();
// 显示详情按钮
$grid-&gt;showViewButton();
// 禁用编辑按钮
$grid-&gt;disableEditButton();
// 显示编辑按钮
$grid-&gt;showEditButton();
// 禁用快捷编辑按钮
$grid-&gt;disableQuickEditButton();
// 显示快捷编辑按钮
$grid-&gt;showQuickEditButton();
// 设置弹窗宽高，默认值为 '700px', '670px'
$grid-&gt;setDialogFormDimensions('50%', '50%');
// 禁用删除按钮
$grid-&gt;disableDeleteButton();
// 显示删除按钮
$grid-&gt;showDeleteButton();
</code></pre>
<h3>设置批量操作按钮 (batchActions)</h3>
<pre><code class="language-php">// 禁用
$grid-&gt;disableBatchActions();
// 显示
$grid-&gt;showBatchActions();
// 禁用批量删除按钮
$grid-&gt;disableBatchDelete();
// 显示批量删除按钮
$grid-&gt;showBatchDelete();</code></pre>
<h3>设置工具栏 (toolbar)</h3>
<pre><code class="language-php">// 禁用
$grid-&gt;disableToolbar();
// 显示
$grid-&gt;showToolbar();</code></pre>
<h3>设置刷新按钮 (refresh)</h3>
<pre><code class="language-php">// 禁用
$grid-&gt;disableRefreshButton();
// 显示
$grid-&gt;showRefreshButton();</code></pre>
<h3>设置分页功能 (paginate)</h3>
<pre><code class="language-php">// 禁用
$grid-&gt;disablePagination();
// 显示
$grid-&gt;showPagination();</code></pre>
<h4>简化分页 (simplePaginate)</h4>
<p>启用 <code>simplePaginate</code> 功能后会使用<code>Laravel</code>的<a href="https://laravel.com/docs/8.x/pagination#simple-pagination">simplePaginate</a>功能进行分页，当数据量较大时可以大幅提升页面的响应速度，但需要注意的是，使用此功能后将不会查询数据表的<strong>总行数</strong>。</p>
<pre><code class="language-php">// 启用
$grid-&gt;simplePaginate();
// 禁用
$grid-&gt;simplePaginate(false);</code></pre>
<h4>设置每页显示行数</h4>
<pre><code class="language-php">// 默认为每页20条
$grid-&gt;paginate(15);</code></pre>
<h4>设置分页选择器选项</h4>
<pre><code class="language-php">$grid-&gt;perPages([10, 20, 30, 40, 50]);
// 禁用分页选择器
$grid-&gt;disablePerPages();</code></pre>
<h3>addTableClass</h3>
<p>通过<code>addTableClass</code>可以给表格的<code>table</code>添加<code>css</code>样式</p>
<pre><code class="language-php">$grid-&gt;addTableClass(['class1', 'class2']);</code></pre>
<h3>设置表格文字居中 (text-center)</h3>
<pre><code class="language-php">$grid-&gt;addTableClass(['table-text-center']);</code></pre>
<h3>显示横向滚动条 (scrollbarX)</h3>
<p>显示表格横向滚动条，默认不显示</p>
<pre><code class="language-php">// 启用
$grid-&gt;scrollbarX();
// 禁用
$grid-&gt;scrollbarX(false);</code></pre>
<h3>设置表格外层容器</h3>
<pre><code class="language-php"> // 更改表格外层容器
$grid-&gt;wrap(function (Renderable $view) {
$tab = Tab::make();
$tab-&gt;add('示例', $view);
$tab-&gt;add('代码', $this-&gt;code(), true);
return $tab;
});</code></pre>
<h2>关联模型</h2>
<p>参考<a href="model-grid-relationship.md">表格关联关系</a></p>