Yii 2 数据展示组件完全实战指南:DetailView、ListView 与 GridView 深入解析
Yii 2 数据展示组件完全实战指南:DetailView、ListView 与 GridView 深入解析
本指南以 docs/guide-fr/output-data-widgets.md(法文版数据组件指南)为核心骨架,结合 yii2 仓库中
framework/widgets与framework/grid目录下的真实源码进行深度印证与扩充。你将掌握 Yii 2 三大数据展示组件(DetailView、ListView、GridView)的完整配置方式、列类型体系、过滤/排序实现原理,以及多网格同页、Pjax 无刷新等进阶实战方案。
Yii 2 提供了一组专用于展示数据的组件(Widgets):DetailView(详情视图)用于展示单条记录,ListView(列表视图)与 GridView(网格视图)用于展示多条记录,并自带分页、排序、过滤等能力。在后台管理系统(Admin)中,GridView 通常是构建数据管理界面的核心组件。本文将以可复制的完整代码示例为主线,带你从零搭建数据展示层,并深入源码理解其底层工作原理。
一、三大组件概览与适用场景
| 组件 | 类名(源码位置) | 数据规模 | 典型用途 |
|---|---|---|---|
| 详情视图 | yii\widgets\DetailView(framework/widgets/DetailView.php) |
单条记录 | 查看文章、用户等单个模型的详细信息页 |
| 列表视图 | yii\widgets\ListView(framework/widgets/ListView.php) |
多条记录 | 博客文章列表、前台信息流等自定义 HTML 布局 |
| 网格视图 | yii\grid\GridView(framework/grid/GridView.php) |
多条记录 | 后台管理表格、带过滤与批量操作的 CRUD 列表 |
从源码结构看,ListView 与 GridView 都继承自抽象基类 yii\widgets\BaseListView(framework/widgets/BaseListView.php),该基类声明了二者共用的核心属性:$dataProvider(数据提供者,必填)、$pager(分页组件配置,默认 LinkPager)、$sorter(排序组件配置,默认 LinkSorter)、$summary(统计信息模板)、$showOnEmpty 与 $emptyText(空数据展示)。因此,分页、排序、统计信息等能力是这两个组件的公共底座,而差异只在于"每一项如何渲染"。
所有组件都消费来自数据提供者(Data Provider)的数据,因此在继续阅读前,建议先了解 ActiveDataProvider、ArrayDataProvider 等提供者的基本概念。
二、DetailView:单记录详情展示
DetailView 用于展示单个数据模型的详细信息。它最适合以规则化格式展示模型,例如将模型的每个属性渲染为表格的一行。模型可以是 yii\base\Model 的实例或其子类(如 ActiveRecord 实例),也可以是关联数组(associative array),甚至是实现 Arrayable 接口或具有公开属性的任意对象(见 DetailView.php 中 $model 的注释)。
2.1 典型用法
echo DetailView::widget([
'model' => $model,
'attributes' => [
'title', // title 属性(纯文本输出)
'description:html', // description 属性,按 HTML 格式输出
[ // 模型所属者的名称(自定义 label 与 value)
'label' => 'Owner',
'value' => $model->owner->name,
],
'created_at:datetime', // 创建时间,格式化为日期/时间
],
]);
2.2 attributes 的两种声明语法
DetailView 通过 $attributes 属性决定展示哪些模型属性以及如何格式化。源码 DetailView.php 中的 normalizeAttributes() 方法完整解析了两种语法:
字符串语法支持 attribute、attribute:format、attribute:format:label 三种形态:
'attributes' => [
'title', // 等价于 'title:text',label 自动取属性标签
'body:html', // 按 HTML 格式化
'created_at:datetime:创建时间', // 显式指定 label
],
源码中对应的正则解析位于 DetailView.php:未显式指定 format 时默认取 'text'(L231),label 未指定时,若模型是 Model 实例则调用 getAttributeLabel(),否则通过 Inflector::camel2words() 自动生成可读标签(L236)。
数组语法支持更细粒度的控制,包含以下键(依据 DetailView.php 的文档注释):
| 键 | 说明 |
|---|---|
attribute |
属性名;当 label 与 value 均未提供时必填 |
label |
显示的标签;缺省时由属性名自动生成 |
value |
要显示的值;缺省时通过 ArrayHelper::getValue() 从模型按属性名取值。自 2.0.11 起支持闭包 function ($model, $widget) {} |
format |
值格式化类型,透传给 Formatter::format() |
visible |
设为 false 时不显示该属性(源码 L225-L228 会直接将其从渲染列表剔除) |
contentOptions |
值单元格(<td>)的 HTML 属性,如 ['class' => 'bg-red'] |
captionOptions |
标签单元格(<th>)的 HTML 属性 |
数组语法的 value 闭包示例(自 2.0.11 起支持):
'attributes' => [
[
'attribute' => 'price',
'value' => function ($model, $widget) {
return $model->price . ' 元';
},
],
],
2.3 格式化与 formatter 组件
DetailView 的格式化工作由 formatter 完成。源码 DetailView.php 显示:若未显式配置 $formatter,则默认取应用组件 Yii::$app->getFormatter();也可以传入一个配置数组由 Yii::createObject() 创建。格式化细节(text、html、datetime、date 等所有格式类型)请参阅数据格式化指南。
2.4 自定义模板与容器
$template 默认值为 '<tr><th{captionOptions}>{label}</th><td{contentOptions}>{value}</td></tr>'(DetailView.php),支持 {label}、{value}、{captionOptions}、{contentOptions} 四个占位符,自 2.0.10 起支持后两者;也可以传入回调函数 function ($attribute, $index, $widget) {}。$options 默认渲染为 <table class="table table-striped table-bordered detail-view">(L116),容器标签可通过 tag 键改变,例如 ['tag' => 'div']。
三、ListView:灵活的自定义列表布局
ListView 用于展示来自数据提供者的数据,每一条模型通过你指定的 itemView 视图渲染。由于组件自带分页、排序等基础能力,它既适合前台信息展示,也适合数据管理界面。
3.1 基本用法
use yii\widgets\ListView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
]);
其中 itemView 指定的视图文件 _post 内容如下:
<?php
use yii\helpers\Html;
use yii\helpers\HtmlPurifier;
?>
<div class="post">
<h2><?= Html::encode($model->title) ?></h2>
<?= HtmlPurifier::process($model->text) ?>
</div>
注意:HtmlPurifier::process() 用于净化富文本、防御 XSS,是渲染用户提交内容的安全做法。
3.2 itemView 中的可用变量
上述视图文件中,当前数据模型以 $model 提供。此外还有以下变量(依据 ListView.php 与 renderItem() 实现 L182-L205):
$model:mixed,当前数据模型$key:mixed,与数据项关联的键值$index:integer,数据项在提供者返回数组中的从零开始的索引$widget:ListView,当前组件实例
3.3 向 itemView 传递额外参数(viewParams)
如果需要向每个条目视图传递附加数据,使用 $viewParams 属性传递键值对:
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
'viewParams' => [
'fullView' => true,
'context' => 'main-page',
// ...
],
]);
这些参数会以同名变量形式注入视图(源码 ListView.php 将 $viewParams 与 model、key、index、widget 合并后交给视图渲染)。
3.4 更多高级属性(源码补充)
$itemOptions:每个数据项容器(默认<div>)的 HTML 属性;可传数组,也可传闭包function ($model, $key, $index, $widget) {}按行动态生成,tag设为false则不渲染容器(ListView.php)。$separator:相邻两项之间的 HTML 分隔符,默认"\n"(L71)。$beforeItem/$afterItem(自 2.0.11 起):在每项渲染前后调用的闭包,签名function ($model, $key, $index, $widget) {},返回null时不输出额外内容(L96-L107)。- 分页、排序、统计信息等公共属性来自父类
BaseListView(framework/widgets/BaseListView.php),例如$summary支持{begin}、{end}、{count}、{totalCount}、{page}、{pageCount}等占位符(L67)。
四、GridView:最强大的网格组件
GridView 是 Yii 中最强大的组件之一,尤其适合快速搭建后台管理界面。它接收数据提供者的数据,通过一组 columns(列)渲染每一行,把全部数据组织成表格。网格中的每一行代表一条数据,每一列通常对应一个属性(部分列也可以是基于属性的复杂表达式或静态文本)。
4.1 最小可用代码
use yii\grid\GridView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo GridView::widget([
'dataProvider' => $dataProvider,
]);
上述代码创建一个数据提供者并交给 GridView,默认自动展示提供者模型的所有属性列(源码 GridView.php 中 columns 未配置时的回退逻辑),且分页、排序无需任何额外配置即可生效。
GridView 的基础外观配置包括:$tableOptions(默认 <a href="https://link.gitcode.com/i/56431912fd208bc885b963ad35aad0a2" target="_blank">'class' => 'table table-striped table-bordered'],[GridView.php)、$options(容器,默认 <a href="https://link.gitcode.com/i/71a217ad871a86e3e2182f7b4034e485" target="_blank">'class' => 'grid-view'])、$caption / $captionOptions(表格标题)、$headerRowOptions / $footerRowOptions(表头/表尾行属性)。过滤行位置由常量控制:FILTER_POS_HEADER、FILTER_POS_FOOTER、FILTER_POS_BODY([GridView.php)。
4.2 列配置(columns)
网格列以 Column 类族表示,通过 GridView::$columns 属性配置。默认列类型是 DataColumn(数据列),用于展示模型属性并支持排序与过滤:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'],
// 简单列:直接使用数据提供者模型中的数据
// 列数据取自模型属性
'id',
'username',
// 一个更复杂的例子
[
'class' => 'yii\grid\DataColumn', // 可省略,因为这是默认值
'value' => function ($data) {
return $data->name; // 若使用 SqlDataProvider 等,$data['name'] 取数组数据
},
],
],
]);
注意:如果
columns配置未指定,Yii 会尝试展示数据提供者模型的全部可用列。
4.3 Column 公共选项:所有列类型共有的配置
所有列类都继承自 yii\grid\Column(framework/grid/Column.php),因此拥有以下公共选项:
-
header:定义表头单元格内容(不经过 HTML 编码,见 Column.php) -
footer:定义表尾单元格内容(L34-L36) -
visible:列是否可见(L47) -
content:传入合法的 PHP 回调,返回单元格内容,格式如下(L38-L43):function ($model, $key, $index, $column) { return 'a string'; }
此外,通过数组可以为容器指定不同的 HTML 属性:
headerOptions(表头单元格<th>属性,L57)footerOptions(表尾单元格属性)filterOptions(过滤单元格属性)contentOptions(数据单元格<td>属性,L68;也支持闭包按行动态生成)
4.4 DataColumn:数据列(默认列类型)
DataColumn 用于展示与排序数据,是默认列类型,因此通常可以省略 class 配置。其关键设置是 format 属性,值对应应用组件 formatter(默认类 yii\i18n\Formatter)的方法:
echo GridView::widget([
'columns' => [
[
'attribute' => 'name',
'format' => 'text'
],
[
'attribute' => 'birthday',
'format' => ['date', 'php:Y-m-d']
],
],
]);
此例中 text 对应 Formatter::asText(),列值作为第一个参数传入;第二个列定义中 date 对应 Formatter::asDate(),列值作为第一个参数,'php:Y-m-d' 作为第二个参数(日期格式)。所有格式化器完整列表见数据格式化指南。
DataColumn 还有以下常用属性(framework/grid/DataColumn.php):
attribute:关联的模型属性名(L48)label:表头显示标签;未设置时若模型是ActiveRecord则用getAttributeLabel(),否则用Inflector::camel2words()生成(L50-L56)encodeLabel:表头标签是否 HTML 编码,默认true(L62)value:字符串或闭包function ($model, $key, $index, $column) {},用于自定义单元格取值(L64-L77)format:默认'text'(L85)enableSorting:是否允许按该列排序,默认true;为true且属性存在于数据提供者sort定义中时,表头会生成排序链接(L91,以及 renderHeaderCellContent() 的实现)sortLinkOptions:排序链接的 HTML 属性(L97)filter:过滤输入控件。未设置时默认生成文本框(样式由filterInputOptions控制,默认['class' => 'form-control', 'id' => null],L120);设为数组则生成下拉列表;设为false则该列不提供过滤(L99-L109)filterAttribute:过滤模型关联属性名,默认与attribute相同(L126-L137)
4.5 ActionColumn:操作列
ActionColumn 为每行显示"查看/更新/删除"等操作按钮:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\ActionColumn',
// 你可以在这里配置附加属性
],
],
]);
可配置属性(见 framework/grid/ActionColumn.php):
-
controller:处理操作的控制器 ID;未设置时使用当前控制器(L42-L47) -
template:定义操作列单元格的组成模板。花括号内的标记被当作操作 ID(即按钮名),会被替换为buttons中对应回调的输出;例如{view}会被buttons['view']的返回结果替换,找不到回调时替换为空字符串。默认标记为{view} {update} {delete}(L63)。例如只保留查看与更新:'template' => '{view} {update}' -
buttons:按钮渲染回调数组。数组键为按钮名(不含花括号),值为渲染回调,签名如下(L65-L89):function ($url, $model, $key) { // 返回按钮的 HTML 代码 }其中
$url是该列为此按钮生成的 URL,$model是当前行正在渲染的模型对象,$key是模型在数据提供者数组中的键。也可以基于数据动态控制按钮输出,例如仅当模型可编辑时显示更新按钮:
'buttons' => [ 'update' => function ($url, $model, $key) { return $model->status === 'editable' ? Html::a('Update', $url) : ''; }, ], -
urlCreator:利用模型信息创建按钮 URL 的回调,签名必须与ActionColumn::createUrl()一致;未设置时使用默认的createUrl()(见 ActionColumn.php 相关说明) -
visibleButtons:各按钮的可见性条件数组。键为按钮名(不含花括号),值为布尔值或匿名函数,签名function ($model, $key, $index) {};未出现在数组中的按钮默认显示。例如:function ($model, $key, $index) { return $model->status === 'editable'; }或者直接传布尔值:
[ 'update' => \Yii::$app->user->can('update') ]
4.6 CheckboxColumn:复选框列
CheckboxColumn 显示一列复选框,用于行选择(批量操作):
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
// ...
[
'class' => 'yii\grid\CheckboxColumn',
// 你可以在这里配置附加属性
],
],
]);
用户勾选后,可通过如下 JavaScript 获取被选中行的主键数组:
var keys = $('#grid').yiiGridView('getSelectedRows');
// keys 是由选中行关联键组成的数组
4.7 SerialColumn:序号列
SerialColumn 从 1 开始依次渲染行号:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'], // <-- 序号列
// ...
],
]);
4.8 自定义列类
除 Yii 内置列类外,你完全可以继承 yii\grid\Column 编写自己的列类,复用 header、footer、visible、content 及各类 HTML 选项能力,再通过 GridView::$dataColumnClass 或直接在 columns 中指定 class 使用。
五、GridView 数据过滤实战
过滤要求 GridView 配合一个代表搜索条件的模型(通常取自网格过滤字段)。使用 ActiveRecord 时的常见做法是创建搜索模型类(可由 Gii 自动生成):该类定义搜索校验规则,并提供返回"按搜索条件调整过查询"的数据提供者的 search() 方法。
5.1 创建搜索模型 PostSearch
为 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()
{
// 绕过父类中的 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;
}
}
提示:关于如何构造过滤查询,参见查询构建器,特别是其中的过滤条件(filter conditions)部分。
5.2 控制器与视图接线
在控制器中使用该搜索模型获取数据提供者:
$searchModel = new PostSearch();
$dataProvider = $searchModel->search(Yii::$app->request->get());
return $this->render('myview', [
'dataProvider' => $dataProvider,
'searchModel' => $searchModel,
]);
在视图中将数据提供者与搜索模型交给 GridView:
echo GridView::widget([
'dataProvider' => $dataProvider,
'filterModel' => $searchModel,
'columns' => [
// ...
],
]);
设置 filterModel 后,每个 DataColumn 的过滤行会自动生成输入控件(默认文本框,样式由 filterInputOptions 控制),输入并提交后即通过 search() 完成过滤。
5.3 独立过滤表单(_search.php)
大多数情况下网格表头的过滤已足够;当需要独立过滤表单时,可创建视图片段 _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中处于注释状态,取消注释即可启用。
5.4 日期范围过滤
独立过滤表单在"按网格中不可见字段过滤"或"特定条件过滤(如日期范围)"时非常有用。要为搜索模型添加非 DB 属性 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, 'createdFrom') ?>
<?= $form->field($model, 'createdTo') ?>
注意:由于非 DB 属性不属于 Post 的校验规则,务必将其加入 safe 规则(如 [['createdFrom', 'createdTo'], 'safe']),否则 load() 后无法通过校验,过滤条件不会生效。
六、关系列:展示、排序与过滤关联模型字段
当在网格中展示 ActiveRecord 时,常常希望显示关联字段(如文章作者姓名)而非其 id。假设 Post 模型有名为 author 的关系(对应 users 表),且关系模型有 name 属性,则可在 columns 中直接写 'author.name'。此时网格能正确展示作者姓名,但排序与过滤默认不生效,需要调整 PostSearch:
启用排序——联表并在数据提供者的 Sort 中添加排序规则:
$query = Post::find();
$dataProvider = new ActiveDataProvider([
'query' => $query,
]);
// 联表关联 `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时,joinWith写法为:$query->joinWith(['author au']);若别名已在关系定义中指定,也可以直接调用
$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], ];另外,当为
Sort指定defaultOrder时需要使用关系名而非别名:$dataProvider->sort->defaultOrder = ['author.name' => SORT_ASC];
说明:关于
joinWith及其后台查询机制的更多信息,参见 ActiveRecord 文档的"联表查询关系"一节。
6.1 使用 SQL 视图实现过滤、排序与展示
另一种更快速、更省事的方法是使用数据库 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
然后创建代表该视图的 ActiveRecord:
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 function attributeLabels()
{
return [
// 在这里定义你的属性标签
];
}
}
此后即可在搜索模型中使用 UserView,无需额外声明排序与过滤属性,所有字段开箱即用。该方案优缺点如下:
- 无需编写排序与过滤条件,一切直接生效;
- 可能大幅提升性能(减少数据量与 SQL 查询次数——每个关联不再需要额外查询);
- 由于只是 UI 与 SQL 视图的简单对接,缺少实体中的业务逻辑;若存在
isActive、isDeleted等影响界面的方法,需要在该类中一并复制实现。
七、单页多个 GridView
同一页面可以放置多个 GridView,但需额外配置,避免彼此的排序与分页链接相互干扰。需要为各网格的排序与分页参数设置不同的参数名——即分别设置数据提供者 sort(yii\data\Sort::$sortParam)与 pagination(yii\data\Pagination::$pageParam)实例的属性。
例如在同一页面同时列出 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,
]);
sortParam 与 pageParam 在 framework/data/Sort.php 与 framework/data/Pagination.php 中定义,默认分别为 sort 与 page;为每个提供者指定唯一名称即可共存。
八、与 Pjax 集成:无刷新过滤与翻页
Pjax 组件允许只更新页面的局部区块而无需整页刷新。可将它用于仅更新 GridView 内容(配合过滤):
use yii\widgets\Pjax;
use yii\grid\GridView;
Pjax::begin([
// Pjax 选项
]);
Gridview::widget([
// GridView 选项
]);
Pjax::end();
Pjax 同样作用于组件内部的链接及 Pjax::$linkSelector 指定的链接。但这对 ActionColumn 的操作链接可能造成问题——点击后整页会被 Pjax 局部替换。要阻止此行为,在配置 ActionColumn::$buttons 时为链接添加 HTML 属性 data-pjax="0",例如:
'buttons' => [
'delete' => function ($url, $model, $key) {
return Html::a('删除', $url, ['data-pjax' => '0']);
},
],
8.1 Gii 生成带 Pjax 的 CRUD
自 Yii 2.0.5 起,Gii 的 CRUD 生成器提供 enablePjax 选项,可通过 Web 界面或命令行使用:
yii gii/crud --controllerClass="backend\\controllers\\PostController" \
--modelClass="common\\models\\Post" \
--enablePjax=1
开启后会生成用 Pjax 包裹 GridView 或 ListView 的代码,过滤与翻页即具备无刷新体验。
九、小结与进一步阅读
本文从源码与实战两个层面完整覆盖了 Yii 2 的三大数据展示组件:
DetailView通过attributes(字符串/数组两种语法)与formatter灵活展示单条记录,模板可完全自定义(见 framework/widgets/DetailView.php);ListView以itemView自由控制每项布局,并通过viewParams注入额外变量(见 framework/widgets/ListView.php);GridView通过columns与四种内置列类型(DataColumn、ActionColumn、CheckboxColumn、SerialColumn)快速构建带分页、排序、过滤的管理表格(见 framework/grid/GridView.php 及其同目录下的列类实现);- 搜索模型 +
andFilterWhere+ 关系联表(joinWith)构成了过滤、排序与关系列的标准方案,SQL 视图则是追求性能与简洁时的替代路线; - 多网格共存通过独立
sortParam/pageParam实现,Pjax 则提供了局部刷新的现代交互体验。
可继续深入阅读的关联文档:数据提供者、数据格式化、ActiveRecord、查询构建器、Gii 代码生成器。测试方面,仓库 tests/framework/grid 与 tests/framework/widgets 目录下提供了各组件与列类的单元测试,可作为理解行为细节的补充材料。