Class yii\grid\GridView
GridView 小部件用于在网格中显示数据。
它提供了诸如 sorting,paging 以及 filtering 数据的特性。
基本的用法如下所示:
<?= GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
'id',
'name',
'created_at:datetime',
// ...
],
]) ?>
网格表的列根据 yii\grid\Column 类进行配置, 这些类是通过 $columns 配置的。
可以使用大量的属性自定义网格视图的外表。
关于 GridView 的更多细节和用法,请参阅 guide article on data widgets。
公共属性
属性 | 类型 | 描述 | 被定义在 |
---|---|---|---|
$afterRow | Closure | 在渲染每个数据模型后调用一次的匿名函数。 它应该类似 $rowOptions 的写法。 函数的返回结果将直接渲染。 | yii\grid\GridView |
$autoIdPrefix | string | The prefix to the automatically generated widget IDs. | yii\base\Widget |
$beforeRow | Closure | 在渲染每个数据模型之前调用一次的匿名函数。 它应该类似 $rowOptions 的写法。 函数的返回结果将直接渲染。 | yii\grid\GridView |
$behaviors | yii\base\Behavior[] | List of behaviors attached to this component | yii\base\Component |
$caption | string | 网格表的标题 | yii\grid\GridView |
$captionOptions | array | 标题元素的 HTML 属性。 | yii\grid\GridView |
$columns | array | 网格列的配置。
每个数组元素表示一个特定的网格列的配置。例如,
` php
[
['class' => SerialColumn::className()],
[
'class' => DataColumn::className(), // this line is optional
'attribute' => 'name',
'format' => 'text',
'label' => 'Name',
],
['class' => CheckboxColumn::className()],
]
如果列是 [[DataColumn]] 的类,"class" 元素将会被省略。
作为快捷方式格式,
可以使用字符串来指定包含 [[DataColumn::attribute|attribute]],
[[DataColumn::format|format]] 和/或 [[DataColumn::label|label]] 选项:`"attribute:format:label"`。
例如,上面的 "name" 列也可以指定为:`"name:text:Name"`。
"format" 和 "label" 都是可选的。如果不存在,它们将采用默认值。
使用快捷方式格式,在简单情况下,列的配置如下所示:
php
[
'id',
'amount:currency:Total Amount',
'created_at:datetime',
]
将 [[dataProvider]] 与活动记录一起使用时,你可以显示相关记录中的值,
例如 `author` 关联的 `name` 属性:
php
// shortcut syntax
'author. |
yii\grid\GridView |
$counter | integer | A counter used to generate $id for widgets. | yii\base\Widget |
$dataColumnClass | string | 如果在配置数据列时没有显示指定类名,这默认数据列的类。 默认为 'yii\grid\DataColumn'。 | yii\grid\GridView |
$dataProvider | yii\data\DataProviderInterface | The data provider for the view. | yii\widgets\BaseListView |
$emptyCell | string | 当单元格的内容为空时显示 HTML。
此属性用于渲染没有定义内容的单元格,
例如,空页脚或过滤单元格。
注意如果数据项为 null ,则 yii\grid\DataColumn 不会使用它。
在这种情况下,
$formatter 的 nullDisplay 属性将用于指示空数据值。 |
yii\grid\GridView |
$emptyText | string|false | The HTML content to be displayed when $dataProvider does not have any data. | yii\widgets\BaseListView |
$emptyTextOptions | array | The HTML attributes for the emptyText of the list view. | yii\widgets\BaseListView |
$filterErrorOptions | array | 渲染每个过滤器错误消息的选项。 当在每个过滤器输入字段旁边渲染错误消息时,这主要由 yii\helpers\Html::error() 使用。 | yii\grid\GridView |
$filterErrorSummaryOptions | array | 用于渲染过滤器错误摘要的选项。 有关于如果指定选项的更多信息,请参阅 yii\helpers\Html::errorSummary()。 | yii\grid\GridView |
$filterModel | yii\base\Model | 保留用户输入的过滤数据的模型。 设置此属性后,网格视图将启用基于列的筛选。 默认情况下,每个数据列都会在顶部显示一个文本字段,用户可以填写该字段以过滤数据。 请注意,为了用于显示用于过滤的输入字段, 列必须设置其 yii\grid\DataColumn::$attribute 属性, 并且该属性应在 $filterModel 的当前场景中处于有效状态或具有 yii\grid\DataColumn::$filter 设置为输入字段的 HTML 代码。 如果未设置此属性(null),则禁用过滤功能。 | yii\grid\GridView |
$filterOnFocusOut | boolean | 无论如何应用过滤器失去焦点。能够通过 yiiGridView JS 管理过滤器 | yii\grid\GridView |
$filterPosition | string | 过滤器是否应显示在网格视图中。有效的值包含: - FILTER_POS_HEADER:过滤器将显示在每列的标题单元格的顶部。 - FILTER_POS_BODY:过滤器将显示在每列的标题单元格的正下方。 - FILTER_POS_FOOTER:过滤器将显示在每列的页脚单元格下方。 | yii\grid\GridView |
$filterRowOptions | array | 过滤器行元素的 HTML 属性。 | yii\grid\GridView |
$filterSelector | string | 用于选择过滤器输入字段的附加 jQuery 选择器 | yii\grid\GridView |
$filterUrl | string|array | 返回过滤结果的 URL。 将调用 yii\helpers\Url::to() 来规范化 URL。如果没有设置,将使用当前控制器方法。 当用户更改任何过滤输入时, 当前过滤输入将作为 GET 参数附加到此 URL。 | yii\grid\GridView |
$footerRowOptions | array | 表格页脚行的 HTML 属性。 | yii\grid\GridView |
$formatter | array|yii\i18n\Formatter | 用于将模型属性格式化为可显示文本的格式化程序。 这可以是 yii\i18n\Formatter 的实例,也可以是用于创建 yii\i18n\Formatter 实例的配置数组。 如果为设置属性,"formatter" 程序组件将会被使用。 | yii\grid\GridView |
$headerRowOptions | array | 表标题行的 HTML 属性。 | yii\grid\GridView |
$id | string | ID of the widget. | yii\base\Widget |
$layout | string | 确定应如何组织网格视图的不同部分的布局。
以下标记将替换为相应的部分内容:
- {summary} :摘要部分。参阅 renderSummary()。
- {errors} :过滤器模型错误摘要。参阅 renderErrors()。
- {items} :列表项。参阅 renderItems()。
- {sorter} :排序。参阅 renderSorter()。
- {pager} :分页。参阅 renderPager()。 |
yii\grid\GridView |
$options | array | The 网格视图的容器标签的 HTML 属性。 "tag" 元素指定容器元素的标记名称,默认为 "div"。 | yii\grid\GridView |
$pager | array | The configuration for the pager widget. | yii\widgets\BaseListView |
$placeFooterAfterBody | boolean | 如果 $showFooter 为 true,是否在 DOM 中将页脚放在 body 后面 | yii\grid\GridView |
$rowOptions | array|Closure | 表主题行的 HTML 属性。
这可以是指定所有主题行的公共 HTML 属性,也可以是返回 HTML 属性的数组的匿名函数。
对于 $dataProvider 返回的每个数据模型,将调用匿名函数一次。
它应该像如下来实现:
` php
function ($model, $key, $index, $grid)
`
- $model :当前渲染的数据模型
- $key :与当前数据模型关联的键值
- $index :$dataProvider 返回的模型数组中数据模型的从零开始的索引
- $grid :GridView 对象 |
yii\grid\GridView |
$showFooter | boolean | 是否显示网格表的页脚部分。 | yii\grid\GridView |
$showHeader | boolean | 是否显示网格表的标题部分。 | yii\grid\GridView |
$showOnEmpty | boolean | 如果 $dataProvider 不返回数据,是否显示网格视图。 | yii\grid\GridView |
$sorter | array | The configuration for the sorter widget. | yii\widgets\BaseListView |
$stack | yii\base\Widget[] | The widgets that are currently being rendered (not ended). | yii\base\Widget |
$summary | string | The HTML content to be displayed as the summary of the list view. | yii\widgets\BaseListView |
$summaryOptions | array | The HTML attributes for the summary of the list view. | yii\widgets\BaseListView |
$tableOptions | array | 属性的 HTML 元素的表格。 | yii\grid\GridView |
$view | yii\web\View | The view object that can be used to render views or view files. | yii\base\Widget |
$viewPath | string | 可以为相对视图名称添加前缀的视图路径。 | yii\base\ViewContextInterface |
公共方法
方法 | 描述 | 被定义在 |
---|---|---|
__call() | Calls the named method which is not a class method. | yii\base\Component |
__clone() | This method is called after the object is created by cloning an existing one. | yii\base\Component |
__construct() | Constructor. | yii\base\BaseObject |
__get() | Returns the value of a component property. | yii\base\Component |
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\Component |
__set() | Sets the value of a component property. | yii\base\Component |
__unset() | Sets a component property to be null. | yii\base\Component |
afterRun() | This method is invoked right after a widget is executed. | yii\base\Widget |
attachBehavior() | Attaches a behavior to this component. | yii\base\Component |
attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component |
beforeRun() | This method is invoked right before the widget is executed. | yii\base\Widget |
begin() | Begins a widget. | yii\base\Widget |
behaviors() | Returns a list of behaviors that this component should behave as. | yii\base\Component |
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\Component |
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\Component |
className() | Returns the fully qualified name of this class. | yii\base\BaseObject |
detachBehavior() | Detaches a behavior from the component. | yii\base\Component |
detachBehaviors() | Detaches all behaviors from the component. | yii\base\Component |
end() | Ends a widget. | yii\base\Widget |
ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
getBehavior() | Returns the named behavior object. | yii\base\Component |
getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component |
getId() | Returns the ID of the widget. | yii\base\Widget |
getView() | Returns the view object that can be used to render views or view files. | yii\base\Widget |
getViewPath() | yii\base\ViewContextInterface | |
hasEventHandlers() | Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\Component |
hasProperty() | Returns a value indicating whether a property is defined for this component. | yii\base\Component |
init() | 初始化网格视图。 此方法将初始化所需的属性值并实例化 $columns 对象。 | yii\grid\GridView |
off() | Detaches an existing event handler from this component. | yii\base\Component |
on() | Attaches an event handler to an event. | yii\base\Component |
render() | Renders a view. | yii\base\Widget |
renderCaption() | 渲染标题元素。 | yii\grid\GridView |
renderColumnGroup() | 渲染列组 HTML。 | yii\grid\GridView |
renderEmpty() | Renders the HTML content indicating that the list view has no data. | yii\widgets\BaseListView |
renderErrors() | 渲染过滤器模型的验证器错误。 | yii\grid\GridView |
renderFile() | Renders a view file. | yii\base\Widget |
renderFilters() | 渲染过滤器。 | yii\grid\GridView |
renderItems() | 渲染网格视图的数据模型。 | yii\grid\GridView |
renderPager() | Renders the pager. | yii\widgets\BaseListView |
renderSection() | Renders a section of the specified name. | yii\grid\GridView |
renderSorter() | Renders the sorter. | yii\widgets\BaseListView |
renderSummary() | Renders the summary text. | yii\widgets\BaseListView |
renderTableBody() | 渲染表主体。 | yii\grid\GridView |
renderTableFooter() | 渲染表尾。 | yii\grid\GridView |
renderTableHeader() | 渲染表头。 | yii\grid\GridView |
renderTableRow() | 使用给定的数据模型和键渲染表行。 | yii\grid\GridView |
run() | 运行小部件。 | yii\grid\GridView |
setId() | Sets the ID of the widget. | yii\base\Widget |
setView() | Sets the view object to be used by this widget. | yii\base\Widget |
trigger() | Triggers an event. | yii\base\Component |
widget() | Creates a widget instance and runs it. | 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 |
Events
事件 | 类型 | 描述 | 被定义在 |
---|---|---|---|
EVENT_AFTER_RUN | yii\base\WidgetEvent | An event raised right after executing a widget. (自版本 2.0.11 可用) | yii\base\Widget |
EVENT_BEFORE_RUN | yii\base\WidgetEvent | An event raised right before executing a widget. (自版本 2.0.11 可用) | yii\base\Widget |
EVENT_INIT | yii\base\Event | An event that is triggered when the widget is initialized via init(). (自版本 2.0.11 可用) | yii\base\Widget |
常量
常量 | 值 | 描述 | 被定义在 |
---|---|---|---|
FILTER_POS_BODY | 'body' | yii\grid\GridView | |
FILTER_POS_FOOTER | 'footer' | yii\grid\GridView | |
FILTER_POS_HEADER | 'header' | yii\grid\GridView |
属性详情
在渲染每个数据模型后调用一次的匿名函数。 它应该类似 $rowOptions 的写法。 函数的返回结果将直接渲染。
在渲染每个数据模型之前调用一次的匿名函数。 它应该类似 $rowOptions 的写法。 函数的返回结果将直接渲染。
网格表的标题
参见 $captionOptions.
网格列的配置。 每个数组元素表示一个特定的网格列的配置。例如,
[
['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 选项:"attribute:format:label"
。
例如,上面的 "name" 列也可以指定为:"name:text:Name"
。
"format" 和 "label" 都是可选的。如果不存在,它们将采用默认值。
使用快捷方式格式,在简单情况下,列的配置如下所示:
[
'id',
'amount:currency:Total Amount',
'created_at:datetime',
]
将 $dataProvider 与活动记录一起使用时,你可以显示相关记录中的值,
例如 author
关联的 name
属性:
// shortcut syntax
'author.name',
// full syntax
[
'attribute' => 'author.name',
// ...
]
如果在配置数据列时没有显示指定类名,这默认数据列的类。 默认为 'yii\grid\DataColumn'。
当单元格的内容为空时显示 HTML。 此属性用于渲染没有定义内容的单元格, 例如,空页脚或过滤单元格。
注意如果数据项为 null
,则 yii\grid\DataColumn 不会使用它。
在这种情况下,
$formatter 的 nullDisplay 属性将用于指示空数据值。
渲染每个过滤器错误消息的选项。 当在每个过滤器输入字段旁边渲染错误消息时,这主要由 yii\helpers\Html::error() 使用。
用于渲染过滤器错误摘要的选项。 有关于如果指定选项的更多信息,请参阅 yii\helpers\Html::errorSummary()。
参见 renderErrors().
保留用户输入的过滤数据的模型。 设置此属性后,网格视图将启用基于列的筛选。 默认情况下,每个数据列都会在顶部显示一个文本字段,用户可以填写该字段以过滤数据。
请注意,为了用于显示用于过滤的输入字段, 列必须设置其 yii\grid\DataColumn::$attribute 属性, 并且该属性应在 $filterModel 的当前场景中处于有效状态或具有 yii\grid\DataColumn::$filter 设置为输入字段的 HTML 代码。
如果未设置此属性(null),则禁用过滤功能。
无论如何应用过滤器失去焦点。能够通过 yiiGridView JS 管理过滤器
过滤器是否应显示在网格视图中。有效的值包含:
- FILTER_POS_HEADER:过滤器将显示在每列的标题单元格的顶部。
- FILTER_POS_BODY:过滤器将显示在每列的标题单元格的正下方。
- FILTER_POS_FOOTER:过滤器将显示在每列的页脚单元格下方。
过滤器行元素的 HTML 属性。
参见 yii\helpers\Html::renderTagAttributes() 有关如何渲染属性的详细信息。.
用于选择过滤器输入字段的附加 jQuery 选择器
返回过滤结果的 URL。 将调用 yii\helpers\Url::to() 来规范化 URL。如果没有设置,将使用当前控制器方法。 当用户更改任何过滤输入时, 当前过滤输入将作为 GET 参数附加到此 URL。
表格页脚行的 HTML 属性。
参见 yii\helpers\Html::renderTagAttributes() 有关于如何渲染属性的详细信息。.
用于将模型属性格式化为可显示文本的格式化程序。 这可以是 yii\i18n\Formatter 的实例,也可以是用于创建 yii\i18n\Formatter 实例的配置数组。 如果为设置属性,"formatter" 程序组件将会被使用。
表标题行的 HTML 属性。
参见 yii\helpers\Html::renderTagAttributes() 有关于如何渲染属性的详细信息。.
确定应如何组织网格视图的不同部分的布局。 以下标记将替换为相应的部分内容:
{summary}
:摘要部分。参阅 renderSummary()。{errors}
:过滤器模型错误摘要。参阅 renderErrors()。{items}
:列表项。参阅 renderItems()。{sorter}
:排序。参阅 renderSorter()。{pager}
:分页。参阅 renderPager()。
The 网格视图的容器标签的 HTML 属性。 "tag" 元素指定容器元素的标记名称,默认为 "div"。
参见 yii\helpers\Html::renderTagAttributes() 有关于如何渲染属性的详细信息。.
如果 $showFooter 为 true,是否在 DOM 中将页脚放在 body 后面
表主题行的 HTML 属性。 这可以是指定所有主题行的公共 HTML 属性,也可以是返回 HTML 属性的数组的匿名函数。 对于 $dataProvider 返回的每个数据模型,将调用匿名函数一次。 它应该像如下来实现:
function ($model, $key, $index, $grid)
$model
:当前渲染的数据模型$key
:与当前数据模型关联的键值$index
:$dataProvider 返回的模型数组中数据模型的从零开始的索引$grid
:GridView 对象
参见 yii\helpers\Html::renderTagAttributes() 有关于如何渲染属性的详细信息。.
是否显示网格表的页脚部分。
是否显示网格表的标题部分。
如果 $dataProvider 不返回数据,是否显示网格视图。
属性的 HTML 元素的表格。
参见 yii\helpers\Html::renderTagAttributes() 有关于如何渲染属性的详细信息。.
方法详情
基于格式为 "attribute:format:label" 的字符串创建 yii\grid\DataColumn 对象。
protected yii\grid\DataColumn createDataColumn($text) | ||
$text | string | 列规范字符串 |
return | yii\grid\DataColumn | 列实例 |
---|---|---|
throws | yii\base\InvalidConfigException | 如果列的规范无效抛出的异常 |
返回网格视图 JS 小部件的选项。
protected array getClientOptions() | ||
return | array | 选项 |
---|
此函数尝试从给定数据中猜测要显示的列 如果没有明确指定 $columns。
protected void guessColumns() |
初始化网格视图。 此方法将初始化所需的属性值并实例化 $columns 对象。
public void init() |
创建列对象并初始化它们。
protected void initColumns() |
渲染标题元素。
public boolean|string renderCaption() | ||
return | boolean|string | 渲染的标题元素或者如果没有渲染就返回 |
---|
渲染列组 HTML。
public boolean|string renderColumnGroup() | ||
return | boolean|string | 列组的 HTML 或者没有渲染列组就返回 |
---|
渲染过滤器模型的验证器错误。
public string renderErrors() | ||
return | string | 渲染结果。 |
---|
渲染过滤器。
public string renderFilters() | ||
return | string | 渲染结果。 |
---|
渲染网格视图的数据模型。
public string renderItems() | ||
return | string | 表的 HTML 代码 |
---|
Renders a section of the specified name.
If the named section is not supported, false will be returned.
public string|boolean renderSection($name) | ||
$name | string | The section name, e.g., |
return | string|boolean | The rendering result of the section, or false if the named section is not supported. |
---|
渲染表主体。
public string renderTableBody() | ||
return | string | 渲染结果。 |
---|
渲染表尾。
public string renderTableFooter() | ||
return | string | 渲染结果。 |
---|
渲染表头。
public string renderTableHeader() | ||
return | string | 渲染结果。 |
---|
使用给定的数据模型和键渲染表行。
public string renderTableRow($model, $key, $index) | ||
$model | mixed | 渲染的数据模型 |
$key | mixed | 与数据模型相关联的键 |
$index | integer | $dataProvider 返回的模型数组中数据模型的从零开始的索引。 |
return | string | 渲染结果 |
---|
运行小部件。
public void run() |