Class yii\widgets\Menu

继承yii\widgets\Menu » 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/widgets/Menu.php

Menu 使用嵌套的 HTML 列表显示多级菜单.

Menu 的主要属性是 $items, 它指定菜单中可能出现的项. 菜单项可以包含指定该菜单项下的子菜单的子项.

Menu 检查当前路由和请求参数, 以切换处于活动状态的某些菜单项.

Note: Menu 仅渲染关于菜单的 HTML 标记, 它可以做任何样式. 你负责提供 CSS 样式, 使其看起来像一个真正的菜单.

以下示例显示如何使用 Menu:

echo Menu::widget([
    'items' => [
        // 重要提示: 即使使用默认动作, 你也需要将 url 指定为'controller/action', 而不仅仅是'controller'.
        ['label' => 'Home', 'url' => ['site/index']],
        // 只有当前路由是'product/index', 'Products'菜单项将会被选中.
        ['label' => 'Products', 'url' => ['product/index'], 'items' => [
            ['label' => 'New Arrivals', 'url' => ['product/index', 'tag' => 'new']],
            ['label' => 'Most Popular', 'url' => ['product/index', 'tag' => 'popular']],
        ]],
        ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
    ],
]);

公共属性

隐藏继承的属性

属性类型描述定义在
$activateItems boolean 是否根据路由设置是否与当前请求的路由相匹配来自动激活项目. yii\widgets\Menu
$activateParents boolean 当相应的子菜单项之一处于活动状态时, 是否激活父菜单项. yii\widgets\Menu
$activeCssClass string 要附加到活动菜单项的 CSS 类. yii\widgets\Menu
$autoIdPrefix string 自动生成的小部件 ID 的前缀. yii\base\Widget
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$counter integer 用于为小部件生成 $id 的计数器. yii\base\Widget
$encodeLabels boolean 菜单项的标签是否应该进行 HTML 编码. yii\widgets\Menu
$firstItemCssClass string 将分配给主菜单或每个子菜单中第一个项目的 CSS 类. yii\widgets\Menu
$hideEmptyItems boolean 是否隐藏空的菜单项. yii\widgets\Menu
$id string|null 小部件的 ID. Note: 此属性的类型在 getter 和 setter 中不同. 有关详细信息, 请参阅 getId()setId(). yii\base\Widget
$itemOptions array 所有菜单项 $items 共享的 HTML 属性列表. yii\widgets\Menu
$items array 菜单项的列表. yii\widgets\Menu
$labelTemplate string 用于渲染不是链接的菜单正文的模板. yii\widgets\Menu
$lastItemCssClass string 将分配给主菜单或每个子菜单中最后一个项目的 CSS 类. yii\widgets\Menu
$linkTemplate string 用于渲染链接菜单的正文的模板. yii\widgets\Menu
$options array 菜单的容器标签的 HTML 属性. yii\widgets\Menu
$params array 用于确定菜单项是否处于活动的参数. yii\widgets\Menu
$route string 用于确定菜单项是否处于活动状态的路由. yii\widgets\Menu
$stack yii\base\Widget[] 当前正在渲染的小部件(未结束). yii\base\Widget
$submenuTemplate string 用于渲染子菜单列表的模板. yii\widgets\Menu
$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\base\Widget
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
render() 渲染视图. yii\base\Widget
renderFile() 渲染视图文件. yii\base\Widget
run() 渲染菜单. yii\widgets\Menu
setId() 设置小部件的 ID. yii\base\Widget
setView() 设置此小部件要使用的视图对象. yii\base\Widget
trigger() 触发事件. yii\base\Component
widget() 创建一个小部件实例并运行它. yii\base\Widget

受保护的方法

隐藏继承的方法

方法描述定义在
isItemActive() 检查菜单项是否处于活动状态. yii\widgets\Menu
normalizeItems() 规范化 $items 的属性以删除不可见的项目并激活某些项目. yii\widgets\Menu
renderItem() 渲染菜单项的内容. yii\widgets\Menu
renderItems() 递归渲染菜单项(不含容器标签). yii\widgets\Menu

事件

隐藏继承的事件

事件类型描述定义在
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

属性详情

$activateItems public 属性

是否根据路由设置是否与当前请求的路由相匹配来自动激活项目.

参见 isItemActive().

public boolean $activateItems true
$activateParents public 属性

当相应的子菜单项之一处于活动状态时, 是否激活父菜单项. 激活的父菜单项也将附加 CSS 类 $activeCssClass.

public boolean $activateParents false
$activeCssClass public 属性

要附加到活动菜单项的 CSS 类.

public string $activeCssClass 'active'
$encodeLabels public 属性

菜单项的标签是否应该进行 HTML 编码.

public boolean $encodeLabels true
$firstItemCssClass public 属性

将分配给主菜单或每个子菜单中第一个项目的 CSS 类. 默认为null, 表示不会分配这样的 CSS 类.

public string $firstItemCssClass null
$hideEmptyItems public 属性

是否隐藏空的菜单项. 空菜单项是未设置url选项并且没有可见的子菜单项的菜单项.

public boolean $hideEmptyItems true
$itemOptions public 属性

所有菜单项 $items 共享的 HTML 属性列表.

如果任何单个菜单项指定了options, 则在使用该属性生成菜单项标签的 HTML 属性之前, 它将与此属性合并.

可以识别以下特殊选项:

  • tag: string, 默认为li, 菜单项容器标签的名称. 设置为false可以禁用容器标签. 请参阅 yii\helpers\Html::tag().

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

public array $itemOptions = []
$items public 属性

菜单项的列表.

每个菜单项都应该是以下结构的数组:

  • label: string, optional, 指定菜单项标签. 当 $encodeLabelstrue时, 标签将被 HTML 编码. 如果未指定标签, 则会使用空字符串.
  • encode: boolean, optional, 该项目的标签是否应进行 HTML 编码. 此参数将覆盖全局 $encodeLabels 参数.
  • url: string or array, optional, 指定菜单项的 url. 将由 yii\helpers\Url::to() 处理. 当设置此项时, 实际的菜单项内容将使用 $linkTemplate 生成; 否则将使用 $labelTemplate.
  • visible: boolean, optional, 该菜单项是否可见. 默认为true.
  • items: array, optional, 指定子菜单项. 其格式与父项相同.
  • active: boolean or Closure, optional, 该菜单项是否处于活动状态(当前选择). 当使用闭包(closure)时, 其签名应该是function ($item, $hasActiveChild, $isItemActive, $widget). 如果项目应该被标记为active, 则闭包(closure)必须返回true, 否则返回false. 如果菜单项处于活动状态, 则其 CSS 类将附加 $activeCssClass. 如果未设置此选项, 则在当前请求由url触发时, 菜单项将自动激活. 有关更多详细信息, 请参阅 isItemActive().
  • template: string, optional, 用于渲染此菜单项内容的模板. 标记{url}将被与此菜单项相关联的 URL 替换, 标记{label}将被菜单项的标签替换. 如果未设置此选项, 将使用 $linkTemplate$labelTemplate.
  • submenuTemplate: string, optional, 用于渲染子菜单列表的模板. 标记{items}将被替换为渲染的子菜单项. 如果未设置此选项, 则将使用 $submenuTemplate.
  • options: array, optional, 菜单容器标签(li)的 HTML 属性.
public array $items = []
$labelTemplate public 属性

用于渲染不是链接的菜单正文的模板.

在此模板中, 标记{label}将被替换为菜单项的标签.

通过 $items 在各个菜单项中设置的template选项将覆盖此属性.

public string $labelTemplate '{label}'
$lastItemCssClass public 属性

将分配给主菜单或每个子菜单中最后一个项目的 CSS 类. 默认:null, 表示不会分配这样的 CSS 类.

public string $lastItemCssClass null
$linkTemplate public 属性

用于渲染链接菜单的正文的模板.

在此模板中, 标记{url}将被替换为相应的链接 URL; 而{label}将被替换为链接文本.

通过 $items 在各个菜单项中设置的template选项将覆盖此属性.

public string $linkTemplate '<a href="{url}">{label}</a>'
$options public 属性

菜单的容器标签的 HTML 属性. 可以识别以下特殊选项:

  • tag: string, 默认为ul, 项目容器标签的标签名称. 设置为false可以禁用容器标签. 请参阅 yii\helpers\Html::tag().

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

public array $options = []
$params public 属性

用于确定菜单项是否处于活动的参数. 如果未设置, 它将使用$_GET.

参见:

public array $params null
$route public 属性

用于确定菜单项是否处于活动状态的路由. 如果未设置, 它将使用当前请求的路由.

参见:

public string $route null
$submenuTemplate public 属性

用于渲染子菜单列表的模板. 在此模板中, 标记{items}将替换为渲染的子菜单项.

public string $submenuTemplate "\n<ul>\n{items}\n</ul>\n"

方法详情

isItemActive() protected 方法

检查菜单项是否处于活动状态.

这是通过检查 $route$params 是否与菜单项的url选项中指定的值匹配来完成的.

当以数组形式指定菜单项的url选项时, 其第一个元素被视为该项的路由, 其余元素为关联参数.

只有当其路由和参数分别与 $route$params 匹配时, 菜单项才会被视为是活动的.

protected boolean isItemActive ( $item )
$item array

要检查的菜单项.

return boolean

菜单项是否处于活动状态.

normalizeItems() protected 方法

规范化 $items 的属性以删除不可见的项目并激活某些项目.

protected array normalizeItems ( $items, &$active )
$items array

要规范化的项目.

$active boolean

是否有活动的子菜单项.

return array

规范化后的菜单项.

renderItem() protected 方法

渲染菜单项的内容.

Note: 此处未渲染容器和子菜单.

protected string renderItem ( $item )
$item array

要渲染的菜单项. 查看该项目中可能包含的数据, 请参阅 $items.

return string

渲染结果.

renderItems() protected 方法

递归渲染菜单项(不含容器标签).

protected string renderItems ( $items )
$items array

递归渲染的菜单项.

return string

渲染结果.

run() public 方法

渲染菜单.

public void run ( )