Class yii\grid\GridView

继承yii\grid\GridView » yii\widgets\BaseListView » yii\base\Widget » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable, yii\base\ViewContextInterface
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/grid/GridView.php

GridView 小部件用于在网格中显示数据.

它提供了 排序, 分页过滤 数据等功能.

基本用法如下所示:

<?= GridView::widget([
    'dataProvider' => $dataProvider,
    'columns' => [
        'id',
        'name',
        'created_at:datetime',
        // ...
    ],
]) ?>

网格表中的列时根据 yii\grid\Column 类进行配置的, 这些类是通过 $columns 配置的.

网格视图的外观可以使用大量的属性进行自定义.

有关 GridView 的更多详细信息和使用信息, 请参阅 权威指南 - 显示数据 - 数据小部件(Data Widgets).

公共属性

隐藏继承的属性

属性类型描述定义在
$afterRow Closure 在渲染每个数据模型之后被调用一次的匿名函数. yii\grid\GridView
$autoIdPrefix string 自动生成的小部件 ID 的前缀. yii\base\Widget
$beforeRow Closure 在渲染每个数据模型之前被调用一次的匿名函数. yii\grid\GridView
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$caption string 网格表的标题. yii\grid\GridView
$captionOptions array 网格表标题元素(caption 标签)的 HTML 属性. yii\grid\GridView
$columns array 网格列配置. yii\grid\GridView
$counter integer 用于为小部件生成 $id 的计数器. yii\base\Widget
$dataColumnClass string 如果在配置数据列时未明确指定类名, 则使用默认数据列类. yii\grid\GridView
$dataProvider yii\data\DataProviderInterface 视图的数据提供者. yii\widgets\BaseListView
$emptyCell string 当单元格内容为空时的 HTML 显示. yii\grid\GridView
$emptyText string|false $dataProvider 没有任何数据时要显示的 HTML 内容. yii\widgets\BaseListView
$emptyTextOptions array 列表视图的 $emptyText 的 HTML 属性. yii\widgets\BaseListView
$filterErrorOptions array 用于渲染每个过滤器错误消息的选项. yii\grid\GridView
$filterErrorSummaryOptions array 用于渲染过滤器错误摘要的选项. yii\grid\GridView
$filterModel yii\base\Model 保留用户输入的过滤器数据的模型. yii\grid\GridView
$filterOnFocusOut boolean 采取什么过滤器来失去焦点. yii\grid\GridView
$filterPosition string 是否应在网格视图中显示过滤器. yii\grid\GridView
$filterRowOptions array 过滤器行元素的 HTML 属性. yii\grid\GridView
$filterSelector string 用于选择过滤器输入字段的其它 jQuery 选择器. yii\grid\GridView
$filterUrl string|array 用于返回过滤结果的 URL. yii\grid\GridView
$footerRowOptions array 表格页脚行(tfoot 中 tr 标签)的 HTML 属性. yii\grid\GridView
$formatter array|yii\i18n\Formatter 用于将模型属性值格式化为可显示文本的格式化程序. yii\grid\GridView
$headerRowOptions array 表格标题行(thead 中 tr 标签)的 HTML 属性. yii\grid\GridView
$id string|null 小部件的 ID. Note: 此属性的类型在 getter 和 setter 中不同. 有关详细信息, 请参阅 getId()setId(). yii\base\Widget
$layout string 确定应如何组织网格视图的不同部分的布局. yii\grid\GridView
$options array 网格视图的容器标签(table 的父级 div 标签)的 HTML 属性. yii\grid\GridView
$pager array 分页小部件的配置. yii\widgets\BaseListView
$placeFooterAfterBody boolean 如果 $showFootertrue, 是否在 DOM 中将页脚放在正文之后. yii\grid\GridView
$rowOptions array|Closure 表格主体行(tbody 中 tr 标签)的 HTML 属性. yii\grid\GridView
$showFooter boolean 是否显示网格表的页脚部分(tfoot 部分). yii\grid\GridView
$showHeader boolean 是否显示网格表的标题部分(thead 部分). yii\grid\GridView
$showOnEmpty boolean 如果 $dataProvider 未返回任何数据, 是否显示网格视图. yii\grid\GridView
$sorter array 排序小部件的配置. yii\widgets\BaseListView
$stack yii\base\Widget[] 当前正在渲染的小部件(未结束). yii\base\Widget
$summary string 将 HTML 内容显示为列表视图的摘要. yii\widgets\BaseListView
$summaryOptions array 列表视图摘要的 HTML 属性. yii\widgets\BaseListView
$tableOptions array 网格表元素(table 标签)的 HTML 属性. yii\grid\GridView
$view yii\web\View 可用于渲染视图或视图文件的视图对象. Note: 此属性的类型在 getter 和 setter 中不同. 有关详细信息, 请参阅 getView()setView(). yii\base\Widget
$viewPath string 包含此小部件的视图文件的目录. 该属性是只读的. yii\base\Widget

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
afterRun() 在执行小部件后立即调用该方法. yii\base\Widget
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
beforeRun() 在执行小部件之前立即调用该方法. yii\base\Widget
begin() 开始一个小部件. yii\base\Widget
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
end() 结束小部件. yii\base\Widget
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getId() 返回小部件的 ID. yii\base\Widget
getView() 返回可用于渲染视图或视图文件的视图对象. yii\base\Widget
getViewPath() 返回包含此小部件的视图文件的目录. yii\base\Widget
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化网格视图. yii\grid\GridView
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
render() 渲染视图. yii\base\Widget
renderCaption() 渲染标题元素(caption). yii\grid\GridView
renderColumnGroup() 渲染列组 HTML. yii\grid\GridView
renderEmpty() 渲染指示列表视图没有数据的 HTML 内容. yii\widgets\BaseListView
renderErrors() 渲染过滤器模型的验证器错误. yii\grid\GridView
renderFile() 渲染视图文件. yii\base\Widget
renderFilters() 渲染过滤器. yii\grid\GridView
renderItems() 渲染网格视图的数据模型. yii\grid\GridView
renderPager() 渲染分页. yii\widgets\BaseListView
renderSection() 渲染指定名称的部分. yii\grid\GridView
renderSorter() 渲染排序. yii\widgets\BaseListView
renderSummary() 渲染摘要文本. yii\widgets\BaseListView
renderTableBody() 渲染表格主体. yii\grid\GridView
renderTableFooter() 渲染表格页脚. yii\grid\GridView
renderTableHeader() 渲染表头. yii\grid\GridView
renderTableRow() 使用给定的数据模型和键来渲染表格行. yii\grid\GridView
run() 运行小部件. yii\grid\GridView
setId() 设置小部件的 ID. yii\base\Widget
setView() 设置此小部件要使用的视图对象. yii\base\Widget
trigger() 触发事件. yii\base\Component
widget() 创建一个小部件实例并运行它. yii\base\Widget

受保护的方法

隐藏继承的方法

方法描述定义在
createDataColumn() 基于attribute:format:label格式的字符串创建 yii\grid\DataColumn 对象. yii\grid\GridView
getClientOptions() 返回网格视图 JS 小部件的选项. yii\grid\GridView
guessColumns() 如果未明确指定 $columns, 则此函数会尝试猜测从给定数据显示的列. yii\grid\GridView
initColumns() 创建并初始化列对象. yii\grid\GridView

事件

隐藏继承的事件

事件类型描述定义在
EVENT_AFTER_RUN yii\base\WidgetEvent 在执行小部件之后立即触发的事件. (available since version 2.0.11) yii\base\Widget
EVENT_BEFORE_RUN yii\base\WidgetEvent 在执行小部件之前触发的事件. (available since version 2.0.11) yii\base\Widget
EVENT_INIT yii\base\Event 当通过 init() 初始化小部件时触发的事件. (available since version 2.0.11) yii\base\Widget

常量

隐藏继承的常量

常量描述定义在
FILTER_POS_BODY 'body' yii\grid\GridView
FILTER_POS_HEADER 'header' yii\grid\GridView

属性详情

$afterRow public 属性

在渲染每个数据模型之后被调用一次的匿名函数.

它应该与 $rowOptions 具有相似的签名. 函数的返回结果将直接渲染.

public Closure $afterRow null
$beforeRow public 属性

在渲染每个数据模型之前被调用一次的匿名函数.

它应该与 $rowOptions 具有相似的签名. 函数的返回结果将直接渲染.

public Closure $beforeRow null
$caption public 属性

网格表的标题.

参见 $captionOptions.

public string $caption null
$captionOptions public 属性

网格表标题元素(caption 标签)的 HTML 属性.

参见:

public array $captionOptions = []
$columns public 属性

网格列配置. 每个数组元素表示一个特定网格列的配置, 例如:

[
    ['class' => SerialColumn::className()],
    [
        'class' => DataColumn::className(), // this line is optional
        'attribute' => 'name',
        'format' => 'text',
        'label' => 'Name',
    ],
    ['class' => CheckboxColumn::className()],
]

如果某列的类是 yii\grid\DataColumn, 则可以省略class元素.

作为一种快捷方式格式, 可以使用字符串来指定仅包含 属性, 格式, 和/或 标签 选项: attribute:format:label.

例如, 上面的name列也可以被指定为: "name:text:Name". formatlabel都是可选的. 如果不存在, 他们将采用默认值.

使用快捷方式格式, 在简单情况下, 列的配置应如下所示:

[
    'id',
    'amount:currency:Total Amount',
    'created_at:datetime',
]

当使用带有活动记录的 $dataProvider 时, 你还可以显示来自相关记录的值. 例如, author关系的name属性:

// 快捷语法
'author.name',
// 完整的语法
[
    'attribute' => 'author.name',
    // ...
]
public array $columns = []
$dataColumnClass public 属性

如果在配置数据列时未明确指定类名, 则使用默认数据列类. 默认为yii\grid\DataColumn.

public string $dataColumnClass null
$emptyCell public 属性

当单元格内容为空时的 HTML 显示.

该属性用于渲染没有定义内容的单元格, 例如, 空的页脚或过滤器单元格.

Note: 如果数据项为null, yii\grid\DataColumn 不会使用此项. 在这种情况下, $formatternullDisplay 属性将用于指示空数据值.

public string $emptyCell '&nbsp;'
$filterErrorOptions public 属性

用于渲染每个过滤器错误消息的选项.

当在每个过滤器输入字段旁边渲染错误消息时, yii\helpers\Html::error() 主要使用此方法.

public array $filterErrorOptions = ['class' => 'help-block']
$filterErrorSummaryOptions public 属性

用于渲染过滤器错误摘要的选项.

有关如何指定选项的更多详细信息, 请参阅 yii\helpers\Html::errorSummary().

参见 renderErrors().

public array $filterErrorSummaryOptions = ['class' => 'error-summary']
$filterModel public 属性

保留用户输入的过滤器数据的模型.

设置此属性后, 网格视图将启用基于列的过滤. 默认情况下, 每个数据列都会在顶部显示一个文本字段, 用户可以填写该字段以过滤数据.

Note: 为了显示用于过滤的输入字段, 列必须具有 yii\grid\DataColumn::$attribute 属性集, 并且该属性在 $filterModel 的当前场景中应处于活动状态, 或设置 yii\grid\DataColumn::$filter 作为输入字段的 HTML 代码.

当此属性未设置(null)时, 则禁用过滤功能.

$filterOnFocusOut public 属性 (可用自版本: 2.0.16)

采取什么过滤器来失去焦点. 保留了通过 yiiGridView JS 管理过滤器的功能.

public boolean $filterOnFocusOut true
$filterPosition public 属性

是否应在网格视图中显示过滤器. 有效值包括:

public string $filterPosition self::FILTER_POS_BODY
$filterRowOptions public 属性

过滤器行元素的 HTML 属性.

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

public array $filterRowOptions = ['class' => 'filters']
$filterSelector public 属性

用于选择过滤器输入字段的其它 jQuery 选择器.

public string $filterSelector null
$filterUrl public 属性

用于返回过滤结果的 URL.

yii\helpers\Url::to() 将被调用以标准化 URL. 如果未设置, 则将使用当前的控制器动作.

当用户对任何过滤器输入进行更改时, 当前过滤输入将作为 GET 参数附加到此 URL.

public string|array $filterUrl null
$footerRowOptions public 属性

表格页脚行(tfoot 中 tr 标签)的 HTML 属性.

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

$formatter public 属性

用于将模型属性值格式化为可显示文本的格式化程序.

这可以是 yii\i18n\Formatter 的实例, 也可以是用于创建 yii\i18n\Formatter 实例的配置数组.

如果未设置此属性, 则将使用应用程序格式化(formatter)组件.

$headerRowOptions public 属性

表格标题行(thead 中 tr 标签)的 HTML 属性.

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

$layout public 属性

确定应如何组织网格视图的不同部分的布局.

以下标记将替换为相应的部分内容:

public string $layout "{summary}\n{items}\n{pager}"
$options public 属性

网格视图的容器标签(table 的父级 div 标签)的 HTML 属性.

tag元素指定容器元素的标签名称, 默认为div.

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

public array $options = ['class' => 'grid-view']
$placeFooterAfterBody public 属性 (可用自版本: 2.0.14)

如果 $showFootertrue, 是否在 DOM 中将页脚放在正文之后.

$rowOptions public 属性

表格主体行(tbody 中 tr 标签)的 HTML 属性.

这可以是为所有主体行指定通用 HTML 属性的数组, 也可以是返回 HTML 属性数组的匿名函数.

对于由 $dataProvider 返回的每个数据模型, 匿名函数将被调用一次. 它应该有以下签名:

function ($model, $key, $index, $grid)
  • $model: 当前正在渲染的数据模型;
  • $key: 与当前数据模型关联的键;
  • $index: 由 $dataProvider 返回的模型数组中的数据模型的从0开始的索引;
  • $grid: GridView 对象.

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

$showFooter public 属性

是否显示网格表的页脚部分(tfoot 部分).

public boolean $showFooter false
$showHeader public 属性

是否显示网格表的标题部分(thead 部分).

public boolean $showHeader true
$showOnEmpty public 属性

如果 $dataProvider 未返回任何数据, 是否显示网格视图.

public boolean $showOnEmpty true
$tableOptions public 属性

网格表元素(table 标签)的 HTML 属性.

参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息.

public array $tableOptions = ['class' => 'table table-striped table-bordered']

方法详情

createDataColumn() protected 方法

基于attribute:format:label格式的字符串创建 yii\grid\DataColumn 对象.

protected yii\grid\DataColumn createDataColumn ( $text )
$text string

列格式字符串.

return yii\grid\DataColumn

列实例.

throws yii\base\InvalidConfigException

如果列格式是无效的.

getClientOptions() protected 方法

返回网格视图 JS 小部件的选项.

protected array getClientOptions ( )
return array

选项.

guessColumns() protected 方法

如果未明确指定 $columns, 则此函数会尝试猜测从给定数据显示的列.

protected void guessColumns ( )
init() public 方法

初始化网格视图.

该方法将初始化所需的属性值并实例化 对象.

public void init ( )
initColumns() protected 方法

创建并初始化列对象.

protected void initColumns ( )
renderCaption() public 方法

渲染标题元素(caption).

public boolean|string renderCaption ( )
return boolean|string

渲染的标题元素, 或如果不应该渲染标题元素时返回false.

renderColumnGroup() public 方法

渲染列组 HTML.

public boolean|string renderColumnGroup ( )
return boolean|string

列组 HTML, 或如果不应该渲染列组时返回false.

renderErrors() public 方法

渲染过滤器模型的验证器错误.

public string renderErrors ( )
return string

渲染结果.

renderFilters() public 方法

渲染过滤器.

public string renderFilters ( )
return string

渲染结果.

renderItems() public 方法

渲染网格视图的数据模型.

public string renderItems ( )
return string

表格的 HTML 代码.

renderSection() public 方法

渲染指定名称的部分.

如果指定的部分不受支持, 则返回false.

public string|boolean renderSection ( $name )
$name string

部分名称, eg, {summary}, {items}.

return string|boolean

该部分的渲染结果; 如果指定的部分不受支持, 则为false.

renderTableBody() public 方法

渲染表格主体.

public string renderTableBody ( )
return string

渲染结果.

renderTableFooter() public 方法

渲染表格页脚.

public string renderTableFooter ( )
return string

渲染结果.

renderTableHeader() public 方法

渲染表头.

public string renderTableHeader ( )
return string

渲染结果.

renderTableRow() public 方法

使用给定的数据模型和键来渲染表格行.

public string renderTableRow ( $model, $key, $index )
$model mixed

要渲染的数据模型.

$key mixed

与数据模型关联的键.

$index integer

$dataProvider 返回的模型数组中的数据模型的从0开始的索引.

return string

渲染结果.

run() public 方法

运行小部件.

public void run ( )