Yii2 数据小部件完全指南:DetailView、ListView 与 GridView 的实战应用与源码剖析

原创2026-09-23 12:14:031,812 阅读
文章标签:后端Web框架

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∣attributes|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∣viewParams|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:空单元格显示内容,默认 '&nbsp;';
  • 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∣Pjax::linkSelector|Pjax::linkSelector]] 指定的链接。但这可能成为 ActionColumn 链接的问题——点击操作按钮时页面整体被 Pjax 拦截。要防止这种情况,请在编辑 [[yii\grid\ActionColumn::buttons∣ActionColumn::buttons|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。

延伸阅读

登录后查看全文
yii2