数据小部件（Data Widgets）

由  创建， 最后一次修改 2016-02-24 数据小部件Yii提供了一套数据小部件?widgets?，这些小部件可以用于显示数据。?DetailView?小部件能够用于显示一条记录数据，?ListView?和GridView?小部件能够用于显示一个拥有分页、排序和过滤功能的一个列表或者表格。DetailViewyii\widgets\DetailView 小部件显示的是单一 yii\widgets\DetailView::$model 数据的详情。它非常适合用常规格式显示一个模型（例如在一个表格的一行中显示模型的每个属性）。 这里说的模型可以是 \yii\base\Model 或者其子类的一个实例，例如子类?active record，也可以是一个关联数组。DetailView使用 yii\widgets\DetailView::$attributes 属性来决定显示模型哪些属性以及如何格式化。 可用的格式化选项，见?formatter section?章节。一个典型的DetailView的使用方法如下：echo DetailView::widget([ 'model' => $model, 'attributes' => [ 'title', // title attribute (in plain text) 'description:html', // description attribute formatted as HTML [ // the owner name of the model 'label' => 'Owner', 'value' => $model->owner->name, ], 'created_at:datetime', // creation date formatted as datetime ],]);ListViewyii\widgets\ListView 小部件用于显示数据提供者?data provider?提供的数据。 每个数据模型用指定的视图文件 yii\widgets\ListView::$itemView 来渲染。 因为它提供开箱即用式的（译者注：封装好的）分页、排序以及过滤这样一些特性，所以它可以很方便地为最终用户显示信息并同时创建数据管理界面。一个典型的用法如下例所示：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?视图文件可包含如下代码：<?phpuse 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，是小部件的实例。假如你需要传递附加数据到每一个视图中，你可以像下面这样用 yii\widgets\ListView::$viewParams 属性传递键值对：echo ListView::widget([ 'dataProvider' => $dataProvider, 'itemView' => '_post', 'viewParams' => [ 'fullView' => true, 'context' => 'main-page', // ... ],]);在视图中，上述这些附加数据也是可以作为变量来使用的。GridView数据网格或者说 GridView 小部件是Yii中最强大的部件之一。如果你需要快速建立系统的管理后台， GridView 非常有用。它从数据提供者?data provider?中取得数据并使用 yii\grid\GridView::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显示每一行的每个属性，每一行的数据是从数据提供者取来的。 展现出来的表格封装了排序以及分页功能。表格列表格的列是通过 yii\grid\Column 类来配置的，这个类是通过 GridView 配置项中的 yii\grid\GridView::columns 属性配置的。根据列的类别和设置的不同，各列能够以不同方式展示数据。 默认的列类是 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 的情形。 }, ], ],]);请注意，假如配置中没有指定 yii\grid\GridView::columns 属性，那么Yii会试图显示数据提供者的模型中所有可能的列。列类通过使用不同类，网格列可以自定义：echo GridView::widget([ 'dataProvider' => $dataProvider, 'columns' => [ [ 'class' => 'yii\grid\SerialColumn', // <-- 这里 // 你还可以在此配置其他属性 ],除了我们下面将要展开讨论的Yii自带的列类，你还可以创建你自己的列类。每个列类是从 yii\grid\Column 扩展而来， 从而在配置网格列的时候，你可以设置一些公共的选项。yii\grid\Column::header 允许为头部行设置内容。yii\grid\Column::footer 允许为尾部行设置内容。yii\grid\Column::visible 定义某个列是否可见yii\grid\Column::content 允许你传递一个有效的PHP回调来为一行返回数据，格式如下：function ($model, $key, $index, $column) { return 'a string';}你可以传递数组来指定各种容器式的HTML选项：yii\grid\Column::headerOptionsyii\grid\Column::footerOptionsyii\grid\Column::filterOptionsyii\grid\Column::contentOptions数据列yii\grid\DataColumn 用于显示和排序