Yii2 数据小部件完全指南:DetailView、ListView 与 GridView 的实战应用与源码剖析
Yii2 数据小部件完全指南:DetailView、ListView 与 GridView 的实战应用与源码剖析
本文围绕 Yii 2 框架的数据小部件(Data Widgets)展开,系统讲解
DetailView(单条记录详情)、ListView(列表展示)与GridView(数据网格)三大核心组件的配置、列定制、排序过滤、关系模型处理与 Pjax 局部刷新。读完本文,你将能熟练运用这些组件搭建带分页、排序、过滤能力的后台数据管理界面,并从源码层面理解其底层渲染机制。
Yii 提供了一套开箱即用的数据小部件(参见 structure-widgets.md),用于把数据模型与数据提供者(Data Provider)优雅地渲染为 HTML。其中 DetailView 负责展示单条记录的详情,ListView 与 GridView 负责展示支持分页、排序和过滤的列表或表格。三者配合 output-data-providers.md 中的数据提供者(如 ActiveDataProvider、ArrayDataProvider、SqlDataProvider),可以快速构建出完整的数据管理界面。
DetailView:单条记录详情展示
[yii\widgets\DetailView|DetailView]] 小部件用于展示单一 [[yii\widgets\DetailView::$model|model]] 的数据详情(源码位于 [framework/widgets/DetailView.php)。它非常适合用常规格式(如表格的每一行对应模型的一个属性)展示模型信息。
这里的模型可以是 [\yii\base\Model]] 或其子类(如 [db-active-record.md 中的 Active Record)的实例,也可以是关联数组。从源码看,$model 属性的类型定义为 array|object,支持 Model 实例、关联数组、实现了 Arrayable 接口的对象,或带有公开可访问非静态属性的普通对象。
DetailView 通过 [yii\widgets\DetailView::attributes]] 属性决定显示模型的哪些属性以及如何格式化,可用的格式化选项参见 [output-formatting.md(格式化器章节)。
一个典型的 DetailView 用法如下:
echo DetailView::widget([
'model' => $model,
'attributes' => [
'title', // title 属性(纯文本)
'description:html', // description 属性按 HTML 格式化
[ // 模型的作者名
'label' => 'Owner',
'value' => $model->owner->name,
'contentOptions' => ['class' => 'bg-red'], // 定制值单元格的 HTML 属性
'captionOptions' => ['tooltip' => 'Tooltip'], // 定制标签单元格的 HTML 属性
],
'created_at:datetime', // 创建时间按 datetime 格式化
],
]);
属性支持三种字符串书写格式:attribute、attribute:format、attribute:format:label,其中 format 会被传给 Formatter::format() 方法将属性值格式化为可显示文本。若以数组形式定义,则支持以下键:
attribute:属性名(当label或value未指定时必填);label:显示标签,缺省时根据属性名自动生成;value:要显示的值,缺省时通过ArrayHelper::getValue()按属性名从模型中取值;自 2.0.11 起可定义为闭包function ($model, $widget);format:值的格式化类型,详见Formatter;visible:是否可见,设为false则该属性不显示;contentOptions:值单元格的 HTML 属性,例如['class' => 'bg-red'];captionOptions:标签单元格的 HTML 属性。
此外,DetailView 还提供了 template(默认 '<tr><th{captionOptions}>{label}</th><td{contentOptions}>{value}</td></tr>',自 2.0.10 起支持 {captionOptions} 与 {contentOptions} 令牌)以及 options(容器标签 HTML 属性,默认 ['class' => 'table table-striped table-bordered detail-view'])等属性,默认渲染为一个 Bootstrap 风格的表格。
需要注意的是,与处理一组模型的 [[yii\widgets\GridView|GridView]] 不同,DetailView 只处理一个模型,$model 可直接在视图中作为变量使用。
结合闭包与权限控制的用法
有些场景下闭包非常有用,例如指定了 visible,同时不想让 value 的结果为 false:
echo DetailView::widget([
'model' => $model,
'attributes' => [
[
'attribute' => 'owner',
'value' => function ($model) {
return $model->owner->name;
},
'visible' => \Yii::$app->user->can('posts.owner.view'),
],
],
]);
当用户无权限时,该属性行整体不渲染;value 闭包在 $model 上执行,可以灵活读取任意关联数据。仓库的测试覆盖见 tests/framework/widgets/DetailViewTest.php。
ListView:列表数据渲染
[yii\widgets\ListView|ListView]] 小部件用于展示数据提供者提供的数据,每个数据模型通过指定的视图文件 [[yii\widgets\ListView::$itemView|itemView]] 渲染(源码位于 [framework/widgets/ListView.php)。由于它开箱即用地支持分页、排序与过滤特性,可以很方便地为最终用户展示信息并创建数据管理界面。
典型的用法如下:
use yii\widgets\ListView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
]);
_post 视图文件可包含如下代码:
<?php
use yii\helpers\Html;
use yii\helpers\HtmlPurifier;
?>
<div class="post">
<h2><?= Html::encode($model->title) ?></h2>
<?= HtmlPurifier::process($model->text) ?>
</div>
在上述视图文件中,当前数据模型 $model 可用;同时还可使用以下变量:
$key:混合类型,与数据项关联的键值;$index:整型,数据提供者返回数组中从 0 起始的数据项索引;$widget:类型为ListView,即当前小部件实例。
itemView 既可以是视图名称,也可以是回调函数 function ($model, $key, $index, $widget)。此外还有 itemOptions(每个数据项容器的 HTML 属性,可传数组或闭包)、separator(相邻两项之间的分隔符,默认 "\n")、beforeItem/afterItem(每项渲染前后调用的闭包,自 2.0.11 起)等属性。
向条目视图传递附加数据
如果需要向每个条目视图传递附加数据,可以通过 [[yii\widgets\ListView::viewParams]] 属性以键值对方式传递:
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
'viewParams' => [
'fullView' => true,
'context' => 'main-page',
// ...
],
]);
在视图中,这些附加数据同样可以直接作为变量使用(例如 $fullView、$context)。
GridView:功能最强大的数据网格
数据网格 GridView 是 Yii 中最强大的小部件之一,非常适合快速构建系统管理后台(源码位于 framework/grid/GridView.php)。它从数据提供者中取得数据,并依据 [[yii\grid\GridView::columns|columns]] 属性配置的一组列,在一个表格中渲染每一行数据。表格中的每一行代表一个数据项,每一列通常表示该数据项的一个属性(某些列也可以是对应属性或静态文本的复杂表达式)。
使用 GridView 的最少代码如下:
use yii\grid\GridView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo GridView::widget([
'dataProvider' => $dataProvider,
]);
上面的代码首先创建数据提供者,然后用 GridView 显示每一行的每个属性,生成的表格自动封装了排序与分页功能。
从源码看,GridView 继承自 BaseListView,提供了大量可定制属性,包括:
caption/captionOptions:表格标题及标题的 HTML 属性;tableOptions:表格元素 HTML 属性,默认['class' => 'table table-striped table-bordered'];options:容器标签 HTML 属性,默认['class' => 'grid-view'];rowOptions:表体行 HTML 属性,可传数组或闭包function ($model, $key, $index, $grid);beforeRow/afterRow:每行渲染前后调用的闭包;showHeader/showFooter:是否显示表头/表尾(默认表尾不显示);showOnEmpty:数据提供者无数据时是否仍显示网格;emptyCell:空单元格显示内容,默认' ';formatter:用于格式化值的Formatter,缺省使用formatter应用组件;filterModel:保存用户过滤数据的模型,设置后开启列过滤;filterUrl:过滤结果的提交 URL,缺省为当前控制器动作;filterPosition:过滤行位置,取值FILTER_POS_HEADER(表头上方)、FILTER_POS_BODY(表头下方,默认)或FILTER_POS_FOOTER(表尾下方);layout:布局模板,支持{summary}、{errors}、{items}、{sorter}、{pager}令牌,默认"{summary}\n{items}\n{pager}"。
GridView::init() 中会将 formatter 归一化为 Formatter 实例(配置数组时通过 Yii::createObject() 创建),并调用 initColumns() 实例化各列对象;run() 中注册 GridViewAsset 并调用 jQuery('#id').yiiGridView(...) 初始化前端交互(见 framework/assets/yii.gridView.js)。
表格列
表格列通过 [yii\grid\Column]] 类配置,是 GridView 配置中 [[yii\grid\GridView::columns|columns]] 属性的组成部分(基类源码位于 [framework/grid/Column.php)。根据列类别和设置的不同,各列能以不同方式展示数据。默认的列类是 [[yii\grid\DataColumn]],用于展示模型的某个属性,并且支持排序和过滤。
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'],
// 数据提供者中所含数据定义的简单列
// 直接使用模型列的数据
'id',
'username',
// 更复杂的列
[
'class' => 'yii\grid\DataColumn', // 由于是默认类型,可以省略
'value' => function ($data) {
return $data->name; // 如果是数组数据则写为 $data['name'](例如使用 SqlDataProvider 时)
},
],
],
]);
注意:如果配置中没有指定 columns 属性,Yii 会试图显示数据提供者模型中所有可能的列。
列类与公共选项
通过使用不同的列类,网格列可以被定制:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\SerialColumn', // <-- 这里指定列类
// 你还可以在此配置其他属性
],
],
]);
除了 Yii 自带的列类,你还可以创建自己的列类。每个列类都从 [[yii\grid\Column]] 扩展而来,因此配置网格列时可以设置以下公共选项:
-
[[yii\grid\Column::header|header]]:允许为表头单元格设置内容(不会被 HTML 编码);
-
[[yii\grid\Column::footer|footer]]:允许为表尾单元格设置内容;
-
[[yii\grid\Column::visible|visible]]:定义某列是否可见,默认
true; -
[[yii\grid\Column::content|content]]:允许传入有效的 PHP 回调为每一行返回数据,格式如下:
function ($model, $key, $index, $column) { return 'a string'; }
还可以通过数组指定各种容器式 HTML 选项:
- [[yii\grid\Column::headerOptions|headerOptions]]
- [[yii\grid\Column::footerOptions|footerOptions]]
- [[yii\grid\Column::filterOptions|filterOptions]]
- [[yii\grid\Column::contentOptions|contentOptions]](可以是数组,也可以是闭包
function ($model, $key, $index, $column),用于按行差异化设置属性)
数据列(DataColumn)
[yii\grid\DataColumn|DataColumn]] 用于显示和排序数据,是默认的列类型,因此使用时可以省略 class 选项(源码位于 [framework/grid/DataColumn.php)。它区分「数据单元格值」(未经格式化的原始值,可用于计算)与「数据单元格内容」(经 format 格式化后可能包含 HTML 的显示内容)。
数据列的主要配置项是 [yii\grid\DataColumn::format|format]] 属性,它的值对应 formatter 应用组件(见 [structure-application-components.md)中的一些方法,默认使用 [[\yii\i18n\Formatter|Formatter]] 应用组件:
echo GridView::widget([
'columns' => [
[
'attribute' => 'name',
'format' => 'text'
],
[
'attribute' => 'birthday',
'format' => ['date', 'php:Y-m-d']
],
'created_at:datetime', // 快捷格式
[
'label' => 'Education',
'attribute' => 'education',
'filter' => ['0' => 'Elementary', '1' => 'Secondary', '2' => 'Higher'],
'filterInputOptions' => ['prompt' => 'All educations', 'class' => 'form-control', 'id' => null]
],
],
]);
在上述代码中,text 对应于 [\yii\i18n\Formatter::asText()]],列的值作为第一个参数传入;第二列定义中 date 对应于 [[\yii\i18n\Formatter::asDate()]],列值作为第一个参数、'php:Y-m-d' 作为第二个参数。更多可用的格式化器列表参见 [output-formatting.md。数据列还支持 "attribute:format:label" 快捷字符串写法,例如 'name:text:Name'、'created_at:datetime'。
数据列的其他关键属性:
label:表头显示的标签,缺省时优先取 ActiveRecord 的getAttributeLabel()(源码见getHeaderCellLabel()的分支逻辑),否则用Inflector::camel2words()生成;encodeLabel:表头标签是否进行 HTML 编码,默认true;value:取值回调function ($model, $key, $index, $column)或字符串属性名(当显示属性与用于排序/过滤的属性不同时很有用);enableSorting:是否允许按该列排序,默认true,且要求属性在数据提供者Sort的定义中(否则表头不渲染排序链接,源码见renderHeaderCellContent());sortLinkOptions:排序链接的 HTML 属性;filter:过滤输入框的 HTML 代码——未设置时自动生成文本框;为数组时生成下拉列表(数组作为选项);为false时该列不显示过滤输入;filterInputOptions:过滤输入框的 HTML 属性,默认['class' => 'form-control', 'id' => null](空id可避免从模型属性取值,提升性能);filterAttribute:与过滤模型关联的属性名,缺省与attribute相同(自 2.0.41 起)。
默认情况下,列的头部通过 [[yii\data\Sort::link]] 渲染排序链接,也可以用 [[yii\grid\Column::header]] 调整;要更改头部文本应设置 label,更多细节参见 DataColumn::getHeaderCellLabel()。
动作列(ActionColumn)
[yii\grid\ActionColumn|ActionColumn]] 用于显示每行的操作按钮(如查看、更新、删除),源码位于 [framework/grid/ActionColumn.php:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\ActionColumn',
// 您可以在此处配置其他属性
],
],
]);
可配置的属性如下:
-
[[yii\grid\ActionColumn::controller|controller]]:执行这些动作的控制器 ID,未设置时使用当前控制器;
-
[[yii\grid\ActionColumn::template|template]]:定义动作列单元格的构建模板,默认
'{view} {update} {delete}'。花括号内的令牌被当作控制器的 action 方法 ID(即按钮名称),会被buttons中对应的渲染回调替换;例如令牌{view}被buttons['view']的返回结果替换,找不到回调则替换为空字符串; -
[[yii\grid\ActionColumn::buttons|buttons]]:按钮渲染回调数组,键为按钮名(不带花括号),值为回调,原型如下:
function ($url, $model, $key) { // 返回按钮的 HTML 代码 }其中
$url是列为该按钮创建的 URL,$model是当前渲染的模型对象,$key是模型在数据提供者数组中的键; -
[[yii\grid\ActionColumn::urlCreator|urlCreator]]:用指定模型信息创建按钮 URL 的回调,原型与
createUrl()一致;自 2.0.10 起可额外接收$index与$column参数。未设置时按钮 URL 由createUrl()创建; -
[[yii\grid\ActionColumn::visibleButtons|visibleButtons]]:控制每个按钮可见性条件的数组,键为按钮名(不带花括号),值为布尔值或匿名函数:
function ($model, $key, $index) { return $model->status === 'editable'; }或者直接传递布尔值:
[ 'update' => \Yii::$app->user->can('update') ]
另外,ActionColumn 还有 buttonOptions(默认按钮的 HTML 属性,自 2.0.4 起)与 icons(按钮图标定义,自 2.0.42 起默认使用 FontAwesome 5 Free 的 SVG 图标)等属性。在 init() 中会调用 initDefaultButtons() 注册默认的 view/update/delete 按钮回调。
复选框列(CheckboxColumn)
[[yii\grid\CheckboxColumn|CheckboxColumn]] 显示一个复选框列。将其加入 columns 配置即可:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
// ...
[
'class' => 'yii\grid\CheckboxColumn',
// 你可以在这里配置更多属性
],
],
]);
用户可通过复选框选择网格中的多行,被选中的行可通过下面的 JavaScript 代码获取:
var keys = $('#grid').yiiGridView('getSelectedRows');
// keys 为与被选行相关联的键组成的数组
该方法的底层实现在 framework/assets/yii.gridView.js 中(getSelectedRows 方法),同文件还实现了全选(checkAllRows)、行选择(checkRow)、过滤事件绑定等前端交互逻辑。网格容器需要设置 id(如 'grid')才能被 jQuery 选择器定位。
序号列(SerialColumn)
[[yii\grid\SerialColumn|SerialColumn]] 渲染行号,从 1 开始自动递增:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'], // <-- 这里
// ...
],
]);
数据排序
注意:本节在官方中文指南中标记为「正在开发中」。这里结合源码给出可用要点:
GridView的排序依赖数据提供者上的 [[yii\data\Sort]] 组件(参见 output-data-providers.md)。默认情况下,只要数据列enableSorting为true且该属性存在于Sort的属性定义中,表头单元格就会渲染排序链接(见DataColumn::renderHeaderCellContent()与Sort::link())。对于自定义列排序(如关系表字段),可通过$dataProvider->sort->attributes[...]追加排序定义,见下文「处理关系型模型」。
数据过滤
为了让 GridView 过滤数据,需要一个模型(见 structure-models.md)从过滤表单接收数据,并调整数据提供者的查询对象以满足搜索条件。使用 Active Record 时,通常的做法是创建一个提供所需功能的搜索模型类(可以用 start-gii.md 中的 Gii 生成)。该类为搜索定义验证规则,并提供返回数据提供者对象的 search() 方法。
为 Post 模型增加搜索能力,可以像下面这样创建 PostSearch 模型:
<?php
namespace app\models;
use Yii;
use yii\base\Model;
use yii\data\ActiveDataProvider;
class PostSearch extends Post
{
public function rules()
{
// 只有在 rules() 函数中声明的字段才可以搜索
return [
[['id'], 'integer'],
[['title', 'creation_date'], 'safe'],
];
}
public function scenarios()
{
// 旁路(bypass)父类中实现的 scenarios() 函数
return Model::scenarios();
}
public function search($params)
{
$query = Post::find();
$dataProvider = new ActiveDataProvider([
'query' => $query,
]);
// 从参数数据中加载过滤条件并验证
if (!($this->load($params) && $this->validate())) {
return $dataProvider;
}
// 增加过滤条件来调整查询对象
$query->andFilterWhere(['id' => $this->id]);
$query->andFilterWhere(['like', 'title', $this->title])
->andFilterWhere(['like', 'creation_date', $this->creation_date]);
return $dataProvider;
}
}
提示:请参阅 db-query-builder.md(尤其是其中的「过滤条件」小节,见 db-query-builder.md#filter-conditions)学习如何构建过滤查询。
在控制器中可以用如下方式为网格视图获取数据提供者:
$searchModel = new PostSearch();
$dataProvider = $searchModel->search(Yii::$app->request->get());
return $this->render('myview', [
'dataProvider' => $dataProvider,
'searchModel' => $searchModel,
]);
然后在视图中将 $dataProvider 和 $searchModel 对象分派给 GridView:
echo GridView::widget([
'dataProvider' => $dataProvider,
'filterModel' => $searchModel,
'columns' => [
// ...
],
]);
GridView 的 filterModel 属性设置后即开启基于列的过滤:每个数据列默认在表头下方(FILTER_POS_BODY)渲染一个文本框(除非该列设置了 filter 为下拉数组或 false)。过滤输入发生变化后,前端 JS 会把过滤条件以 GET 参数追加到 filterUrl 并重新请求。filterOnFocusOut(自 2.0.16 起)控制是否在输入框失去焦点时触发过滤,默认 true。
单独过滤表单
大多数时候使用 GridView 标头过滤器就足够了,但如果需要一个单独的过滤器表单,也可以轻松添加。创建部分视图 _search.php:
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
/**
* @var \yii\web\View $this
* @var \app\models\PostSearch $model
* @var \yii\widgets\ActiveForm $form
*/
?>
<div class="post-search">
<?php $form = ActiveForm::begin([
'action' => ['index'],
'method' => 'get',
]); ?>
<?= $form->field($model, 'title') ?>
<?= $form->field($model, 'creation_date') ?>
<div class="form-group">
<?= Html::submitButton('Search', ['class' => 'btn btn-primary']) ?>
<?= Html::submitButton('Reset', ['class' => 'btn btn-default']) ?>
</div>
<?php ActiveForm::end(); ?>
</div>
并将其包含在 index.php 视图中:
<?= $this->render('_search', ['model' => $searchModel]) ?>
注意:如果使用 Gii 生成 CRUD 代码,默认会生成单独的过滤器表单(
_search.php),但在index.php视图中它已经被注释掉了,取消注释即可使用。
当需要按某些不在 GridView 中显示的字段过滤、或需要特殊筛选条件(如日期范围)时,单独过滤表单非常有用。对于按日期范围过滤,可以将非数据库属性 createdFrom 和 createdTo 添加到搜索模型:
class PostSearch extends Post
{
/**
* @var string
*/
public $createdFrom;
/**
* @var string
*/
public $createdTo;
}
在 search() 方法中扩展查询条件:
$query->andFilterWhere(['>=', 'creation_date', $this->createdFrom])
->andFilterWhere(['<=', 'creation_date', $this->createdTo]);
并将对应字段添加到过滤器表单:
<?= $form->field($model, 'creationFrom') ?>
<?= $form->field($model, 'creationTo') ?>
处理关系型模型
在网格视图中显示 Active Record 数据时,经常需要显示关联表的列值,例如显示发帖者(author)的名字而不是其 id。当 Post 模型有关联属性 author(Post 中用 hasOne 定义 getAuthor()),且作者模型有属性 name 时,可以在 [[yii\grid\GridView::$columns]] 中定义属性名 author.name。此时网格视图能显示作者名,但默认不支持按作者名排序和过滤,需要调整 PostSearch 模型来添加此功能。
为了使关联列能够排序,需要连接关系表并添加排序规则到数据提供者的排序组件:
$query = Post::find();
$dataProvider = new ActiveDataProvider([
'query' => $query,
]);
// 连接与 `users` 表相关联的 `author` 表
// 并将 `users` 表的别名设为 `author`
$query->joinWith(['author' => function($query) { $query->from(['author' => 'users']); }]);
// 自 2.0.7 起,上一行可以简化为 $query->joinWith('author AS author');
// 使关联字段可以排序
$dataProvider->sort->attributes['author.name'] = [
'asc' => ['author.name' => SORT_ASC],
'desc' => ['author.name' => SORT_DESC],
];
// ...
过滤同样需要像上面一样调用 joinWith。还需要在属性和规则中定义该列:
public function attributes()
{
// 添加关联字段到可搜索属性集合
return array_merge(parent::attributes(), ['author.name']);
}
public function rules()
{
return [
[['id'], 'integer'],
[['title', 'creation_date', 'author.name'], 'safe'],
];
}
然后在 search() 方法中添加一个额外过滤条件:
$query->andFilterWhere(['LIKE', 'author.name', $this->getAttribute('author.name')]);
信息:上面的代码中,我们使用相同的字符串作为关联名称和表别名;但当表别名与关联名称不相同时,需要注意区分在哪使用别名、在哪使用关联名称。一个简单的规则是:在每个构建数据库查询的地方使用别名,而在所有与定义相关的地方(如
attributes()和rules())使用关联名称。例如,使用
au作为作者关系表的别名,联查语句写成:$query->joinWith(['author' => function($query) { $query->from(['au' => 'users']); }]);当别名已经在关联函数中定义时,也可以直接调用
$query->joinWith(['author']);。在过滤条件中必须使用别名,但属性名称保持不变:
$query->andFilterWhere(['LIKE', 'au.name', $this->getAttribute('author.name')]);排序定义也同样如此:
$dataProvider->sort->attributes['author.name'] = [ 'asc' => ['au.name' => SORT_ASC], 'desc' => ['au.name' => SORT_DESC], ];同样,当通过 [[yii\data\Sort::defaultOrder|defaultOrder]] 指定默认排序时,需要使用关联名称而不是别名:
$dataProvider->sort->defaultOrder = ['author.name' => SORT_ASC];
信息:关于
joinWith及后台执行查询的更多信息,参见 db-active-record.md#joining-with-relations。
使用 SQL 视图过滤、排序和显示数据
还有另一种更快、更实用的方法:SQL 视图。例如要在 GridView 中显示用户及其简介,可以创建如下 SQL 视图:
CREATE OR REPLACE VIEW vw_user_info AS
SELECT user.*, user_profile.lastname, user_profile.firstname
FROM user, user_profile
WHERE user.id = user_profile.user_id
然后创建代表该视图的 Active Record 模型:
<?php
namespace app\models\views\grid;
use yii\db\ActiveRecord;
class UserView extends ActiveRecord
{
/**
* @inheritdoc
*/
public static function tableName()
{
return 'vw_user_info';
}
public static function primaryKey()
{
return ['id'];
}
/**
* @inheritdoc
*/
public function rules()
{
return [
// 在这定义你的规则
];
}
/**
* @inheritdoc
*/
public static function attributeLabels()
{
return [
// 在这定义你的属性标签
];
}
}
之后可以直接使用这个 UserView Active Record 和搜索模型,无需为排序和过滤属性附加规则,所有属性开箱即用。这种方法有利有弊:
- 优点:不需要分别指定不同的排序和过滤条件,一切已封装好;
- 优点:可能更快,因为数据量和 SQL 查询执行都得到优化(每个关联数据不需要额外的查询);
- 缺点:SQL 视图只是实体到 UI 的简单映射,可能缺乏实体中的某些逻辑。如果有一些诸如
isActive、isDeleted或其他影响 UI 的方法,也需要在该类中复制它们。
单个页面多个网格视图
可以在单个页面中使用多个网格视图,但需要一些额外配置,使它们互不干扰。使用多个 GridView 实例时,必须为生成的排序和分页对象配置不同的参数名,以便每个网格视图有各自独立的排序与分页。可以通过设置 [[yii\data\Sort::sortParam|sortParam]] 和 [[yii\data\Pagination::pageParam|pageParam]] 实现,它们分别对应数据提供者的 [[yii\data\BaseDataProvider::sort|sort]] 和 [[yii\data\BaseDataProvider::pagination|pagination]] 实例。
假如要同时显示 Post 和 User 模型(它们已准备好 $postProvider 和 $userProvider 两个数据提供者),做法如下:
use yii\grid\GridView;
$userProvider->pagination->pageParam = 'user-page';
$userProvider->sort->sortParam = 'user-sort';
$postProvider->pagination->pageParam = 'post-page';
$postProvider->sort->sortParam = 'post-sort';
echo '<h1>Users</h1>';
echo GridView::widget([
'dataProvider' => $userProvider,
]);
echo '<h1>Posts</h1>';
echo GridView::widget([
'dataProvider' => $postProvider,
]);
在 GridView 中使用 Pjax
[yii\widgets\Pjax|Pjax]](源码位于 [framework/widgets/Pjax.php)允许只更新页面的某个部分而不重新加载整个页面。使用过滤器时,可以用它仅更新 GridView 的内容:
use yii\widgets\Pjax;
use yii\grid\GridView;
Pjax::begin([
// PJax options
]);
GridView::widget([
// GridView options
]);
Pjax::end();
Pjax 也适用于 Pjax 小部件之间的链接以及 [[yii\widgets\Pjax::linkSelector]] 指定的链接。但这可能成为 ActionColumn 链接的问题——点击操作按钮时页面整体被 Pjax 拦截。要防止这种情况,请在编辑 [[yii\grid\ActionColumn::buttons]] 属性时给链接添加 HTML 属性 data-pjax="0"。
在 Gii 中使用 Pjax 的 GridView/ListView
从 2.0.5 开始,start-gii.md 中的 Gii CRUD 生成器有一个 enablePjax 选项,可以通过 Web 界面或命令行使用:
yii gii/crud --controllerClass="backend\\controllers\PostController" \
--modelClass="common\\models\\Post" \
--enablePjax=1
这会生成一个由 Pjax 小部件包含的 GridView 或 ListView。
延伸阅读
- 本仓库相关源码与测试:
- 小部件实现:framework/widgets/DetailView.php、framework/widgets/ListView.php、framework/widgets/BaseListView.php、framework/widgets/Pjax.php;
- 网格实现:framework/grid/GridView.php、framework/grid/Column.php、framework/grid/DataColumn.php、framework/grid/ActionColumn.php、framework/grid/CheckboxColumn.php、framework/grid/SerialColumn.php;
- 前端交互:framework/assets/yii.gridView.js;
- 测试用例:tests/framework/grid/GridViewTest.php、tests/framework/widgets/ListViewTest.php、tests/framework/widgets/DetailViewTest.php。
- 相关主题:output-data-providers.md(数据提供者)、output-formatting.md(数据格式化)、db-query-builder.md(查询构建器与过滤条件)、structure-widgets.md(小部件基础)。