buttflattery/yii2-multimenu

一个基于 yii\widgets\Menu 的 Yii2 小部件,创建基于导航菜单,并提供多种布局选项:大下拉菜单、左侧菜单和固定下拉菜单。

1.0.0 2020-02-15 16:34 UTC

This package is auto-updated.

Last update: 2024-09-14 03:58:42 UTC


README

此仓库是做什么的?

一个基于 yii\widgets\Menu 的 Yii2 小部件,创建基于导航菜单,并提供多种布局选项,包括 大下拉 风格的顶部导航、左侧菜单 导航和 固定下拉 脚部菜单。它使用多个第三方插件来动画菜单。它提供了一个额外的辅助组件,用于从模型中构建菜单。

preview

使用的第三方库

关于 Bootstrap 版本的使用

该扩展会检测你是否正在使用 yiisoft/yii2-bootstrapyiisoft/yii2-bootstrap4,并为扩展加载相应的资源。它首先检查 "yiisoft/yii2-bootstrap4" 是否存在,如果存在,则加载 bootstrap4 资源,否则将回退到使用 bootstrap3。因此,请确保你正在遵循正确的指南使用 yiisoft/yii2-bootstrap4",并从你的 composer.json 中删除 "yiisoft/yii2-bootstrap": "~2.0.0", 并将这里的 minimum-stability:"dev" 改变。这里是完整的 指南

如何设置包

使用 composer 安装扩展

php composer.phar require  buttflattery/yii2-multimenu "@dev"

或在 composer.json 文件的 require 部分添加

"buttflattery/yii2-multimenu":"@dev"

演示

用法

<?php
    echo MultiMenu::widget(
        [
            'activeCssClass' => 'active',
            'items' => Yii::$app->menuhelper->getMenuItems(),
            'brandLabel' => 'Left Navigation',
            'brandImage' => '/path/to/image/src',// path to image , can be base64encoded image content too
            'brandUrl' => 'https://yii2plugins.omaraslam.com',
            'activateParents' => true,
            'layoutTemplate'=>'{multimenu}{brand}',
            'enableIcons'=>true,
            'multimenuOptions' => [
                'theme' => MultiMenu::THEME_LEFTNAV,
                'mobileView' => true,
                MultiMenu::THEME_LEFTNAV => [
                    'position'=>MultiMenu::LEFT_NAV_FIXED,
                    'slimScroll' => [
                        'scrollColor' => 'rgba(0,0,0,0.75)'
                    ]
                ]
            ]
        ]
    );
?>

小部件的可用选项

你可以使用 yii\widgets\Menu 的默认选项,以及以下选项

$brandImage (string|bool)

品牌图像的 src 或不使用时的 false。注意,此参数将覆盖 $this->brandLabel 参数。默认值为 false

$brandLabel (string|bool)

品牌文本或不使用时的 false。注意,这不是 HTML 编码的。默认值为 false

$brandOptions (array)

品牌链接的 HTML 属性。有关属性渲染的详细信息,请参阅 \yii\helpers\Html::renderTagAttributes()

$brandUrl (bool)

品牌超链接标签的 URL。此参数将由 [[\yii\helpers\Url::to()]] 处理,并用于品牌链接的 "href" 属性。默认值为 false,这意味着将使用 [[\yii\web\Application::homeUrl]]。如果你想完全不使用链接,可以将其设置为 null

$containerCssClasses (array)

容器 HTML 选项。

$layoutTemplate (string)

用于绘制菜单和调整品牌及菜单项位置的布局模板。默认值为 {brand}{multimenu}

$enableIcons (bool)

如果默认图标应与菜单标签一起启用。它使用 Multmenu::DEFAULT_ICON,其值为 <i class="ion-android-menu"></i>

$multimenuOptions (数组)

您可以将特定于插件的设置传递到这里,以便根据您使用的菜单类型进行设置。

  • theme (字符串)

    您想要使用的菜单主题,可以是 bigdropleftnavdropup 中的任何一个,您可以使用可用的常量 THEME_BIGDROPTHEME_LEFTNAVTHEME_DROPUP。请参阅可用常量部分。

  • themeColorFile (字符串)

    您想要与菜单一起加载的主题颜色文件的作用域名称,您可以通过此选项自定义菜单类并加载。默认值为空 ''。请参阅维基百科以创建主题文件。

  • mobileView (布尔值)

    如果启用,菜单将在移动视图中做出响应。当您想在同一页面上使用两个菜单,其中一个菜单仅显示在移动视图中时,此选项很有用,您可以关闭另一个菜单。默认值为 true

  • enableWavesPlugin (布尔值)

    如果当点击菜单项时应该启用 Waves 插件。默认值为 true

  • wavesEffect (字符串)

    波浪效果的颜色,请参阅 https://materialize.node.org.cn/waves.html#! 。默认值为 waves-cyan

  • wavesType (字符串) circular|default

    波浪类型效果,circulardefault。默认值为 default。请参阅常量部分,以查看您可以使用的所有可用效果。

  • mobileBreakPoint (整数)

    移动视图断点,其中 JavaScript 插件应重新计算大小。默认值为 1200。(注意:除非您知道自己在做什么,否则不要更改此选项,因为更改它将需要您更新主题的媒体查询。

有一些菜单/主题特定选项仅适用于特定类型的菜单。请参阅以下详细信息。

  • bigdrop (数组)

    仅适用于 bigdrop 菜单,接受以下设置。

    • enableTransitionEffects (布尔值):在菜单上启用过渡效果,使用 animate.css。默认值为 true

    • transitionEffect (字符串):显示菜单的过渡效果。默认值 flipInX。请参阅 animate.css 以了解过渡效果类型。

    • transitionDelay (字符串):过渡动画速度 "fast"|"faster"|"slow"|"slower"|""。默认值为 faster。请参阅可用常量。

  • dropup (数组)

    接受与上面相同的设置集,但使用不同的默认值

    • enableTransitionEffects => true
    • transitionEffect => 'fadeIn`
    • transitionDelay => 'slow'
  • leftnav (数组)

    接受与上面相同的设置集,但具有不同的默认值,并为 leftnav 提供一些额外选项。

    • enableTransitionEffects => true

    • transitionEffect => 'fadeIn`

    • transitionDelay => 'slow'

    • position (字符串) default|fixed|absolute:左菜单的位置,默认值为 default,并且 leftnav 将相对于其父容器进行渲染。

    • slimScroll (数组):用于左导航的 slimscroll 插件的选项。

      • scrollColor (字符串):滚动条颜色,默认值为 rgba(0,0,0,0.8)

      • scrollWidth (字符串):滚动条宽度,默认值为 4px

      • scrollAlwaysVisible (布尔值):如果为 true,则滚动条始终可见,默认值为 false

      • scrollBorderRadius:滚动条边框半径,默认值为 0

      • scrollRailBorderRadius : 设置轨道的边框半径,默认值是 0

      • scrollActiveItemWhenPageLoad : 如果设置为 true,页面加载后始终滚动到活动菜单项链接,默认值是 true

请注意,如果您手动提供以下菜单的 items 数组,当指定进一步打开菜单的子菜单的 label 时,您不应留空 url,而应使用以下示例中的 javascript::void(0)

带有品牌文本的BigDrop最小选项

bigdrop菜单使用正常的下拉菜单作为前两级/子级,

  • 一级
    • 二级

这意味着您需要3个或更多级别/子级来激活bigdrop菜单,并且将支持无限级别。请参阅下面的$items列表。

<?php
    use buttflattery\multimenu\MultiMenu;

    $items = [
            ['label' => 'Home', 'url' => ['/site/index']],
            ['label' => 'About', 'url' => ['/site/about']],
            ['label' => 'Contact', 'url' => ['/site/contact']],
            [
                'label' => 'Dropdown',
                'url' => 'javascript:void(0)',
                'items' => [
                    ['label' => 'Level 2  Dropdown A', 'url' => '#.'],
                    ['label' => 'Level 2  Dropdown B', 'url' => '#.'],
                    [
                        'label' => 'Level 3  Dropdown C',
                        'url'=>'javascript:void(0)'
                        'items'=>[
                            [
                                ['label' => 'Level 4  Dropdown A', 'url' => '#.'],
                                ['label' => 'Level 4  Dropdown B', 'url' => '#.'],
                                ['label' => 'Level 4  Dropdown C', 'url' => '#.'],
                                ['label' => 'Level 4  Dropdown D', 'url' => '#.'],
                                ['label' => 'Level 4  Dropdown E', 'url' => '#.'],
                            ]
                        ]
                    ],
                ],
            ],
            Yii::$app->user->isGuest ? (
                ['label' => 'Login', 'url' => ['/site/login']]
            ) : (
                '<li>'
                . Html::beginForm(['/site/logout'], 'post')
                . Html::submitButton(
                    'Logout (' . Yii::$app->user->identity->username . ')',
                    ['class' => 'btn btn-link logout']
                )
                . Html::endForm()
                . '</li>'
        ),
    ];

    echo MultiMenu::widget(
        [
            'activeCssClass' => 'active',
            'items' => $items,
            'layoutTemplate' => '{multimenu}{brand}',
            'enableIcons'=>true,
            'brandUrl' => 'https://plugins.omaraslam.com',
            'brandLabel'=>'Yii2 Multimenu',
            'activateParents' => true,
            'multimenuOptions' => [
                'theme' => MultiMenu::THEME_BIGDROP,
            ],
        ]
    );

?>

左侧导航栏带有品牌图片的最小选项

<?php
    use buttflattery\multimenu\MultiMenu;
    $items = [
            ['label' => 'Home', 'url' => ['/site/index']],
            ['label' => 'About', 'url' => ['/site/about']],
            ['label' => 'Contact', 'url' => ['/site/contact']],
            [
                'label' => 'Dropdown',
                'url' => 'javascript:void(0)',
                'items' => [
                    ['label' => 'Level 1  Dropdown A', 'url' => '#'],
                    ['label' => 'Level 1  Dropdown B', 'url' => '#'],
                ],
            ],
            Yii::$app->user->isGuest ? (
                ['label' => 'Login', 'url' => ['/site/login']]
            ) : (
                '<li>'
                . Html::beginForm(['/site/logout'], 'post')
                . Html::submitButton(
                    'Logout (' . Yii::$app->user->identity->username . ')',
                    ['class' => 'btn btn-link logout']
                )
                . Html::endForm()
                . '</li>'
        ),
    ];

    echo MultiMenu::widget(
        [
            'activeCssClass' => 'active',
            'items' => $items,
            'brandLabel' => 'Left Navigation',
            //using base64 encoded image content for brand image
            'brandImage' => 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACgAAAAoCAYAAACM/rhtAAAB+0lEQVR4AcyYg5LkUBhG+1X2PdZGaW3btm3btm3bHttWrPomd1r/2Jn/VJ02TpxcH4CQ/dsuazWgzbIdrm9dZVd4pBz4zx2igTaFHrhvjneVXNHCSqIlFEjiwMyyyOBilRgGSqLNF1jnwNQdIvAt48C3IlBmHCiLQHC2zoHDu6zG1iXn6+y62ScxY9AODO6w0pvAqf23oSE4joOfH6OxfMoRnoGUm+de8wykbFt6wZtA07QwtNOqKh3ZbS3Wzz2F+1c/QJY0UCJ/J3kXWJfv7VhxCRRV1jGw7XI+gcO7rEFFRvdYxydwcPsVsC0bQdKScngt4iUTD4Fy/8p7PoHzRu1DclwmgmiqgUXjD3oTKHbAt869qdJ7l98jNTEblPTkXMwetpvnftA0LLHb4X8kiY9Kx6Q+W7wJtG0HR7fdrtYz+x7iya0vkEtUULIzCjC21wY+W/GYXusRH5kGytWTLxgEEhePPwhKYb7EK3BQuxWwTBuUkd3X8goUn6fMHLyTT+DCsQdAEXNzSMeVPAJHdF2DmH8poCREp3uwm7HsGq9J9q69iuunX6EgrwQVObjpBt8z6rdPfvE8kiiyhsvHnomrQx6BxYUyYiNS8f75H1w4/ISepDZLoDhNJ9cdNUquhRsv+6EP9oNH7Iff2A9g8h8CLt1gH0Qf9NMQAFnO60BJFQe0AAAAAElFTkSuQmCC',
            'brandUrl' => 'http://omaraslam.com',
            'activateParents' => true,
            'layoutTemplate'=>'{multimenu}{brand}',
            'enableIcons'=>true,
            'multimenuOptions' => [
                'theme' => MultiMenu::THEME_LEFTNAV,
                'mobileView' => true,
                MultiMenu::THEME_LEFTNAV => [
                    'position'=>MultiMenu::LEFT_NAV_FIXED,
                    'slimScroll' => [
                        'scrollColor' => 'rgba(0,0,0,0.75)'
                    ]
                ]
            ]
        ]
    );
?>

带有自定义颜色主题的Dropup菜单

<?php
    use buttflattery\multimenu\MultiMenu;

    $items = [
            ['label' => 'Home', 'url' => ['/site/index']],
            ['label' => 'About', 'url' => ['/site/about']],
            ['label' => 'Contact', 'url' => ['/site/contact']],
            [
                'label' => 'Dropdown',
                'url' => 'javascript:void(0)',
                'items' => [
                    ['label' => 'Level 1  Dropdown A', 'url' => '#'],
                    ['label' => 'Level 1  Dropdown B', 'url' => '#'],
                ],
            ],
            Yii::$app->user->isGuest ? (
                ['label' => 'Login', 'url' => ['/site/login']]
            ) : (
                '<li>'
                . Html::beginForm(['/site/logout'], 'post')
                . Html::submitButton(
                    'Logout (' . Yii::$app->user->identity->username . ')',
                    ['class' => 'btn btn-link logout']
                )
                . Html::endForm()
                . '</li>'
        ),
    ];

    echo MultiMenu::widget(
        [
            'activeCssClass' => 'active',
            'items' => Yii::$app->menuhelper->getMenuItems('menu_name'),
            'activateParents' => true,
            'brandLabel' => 'Yii2 Multimenu',
            'enableIcons'=>true,
            'brandUrl' => 'https://plugins.omaraslam.com',
            'layoutTemplate'=>'{multimenu}{brand}',
            'multimenuOptions' => [
                'theme' => MultiMenu::THEME_DROPUP,
                'themeColorFile' => \app\assets\DropUpBisqueRed::class,
                'mobileView' => true,
                MultiMenu::THEME_DROPUP => [
                    'transitionEffect' => MultiMenu::ANIMATE_DEFAULT,
                ],
            ],
        ]
    );
?>

您的主题资产类代码

<?php
// @codingStandardsIgnoreStart
namespace app\assets;

use buttflattery\multimenu\assetbundles\bs3\ThemeDropUpAsset;

class DropUpBisqueRed extends ThemeDropUpAsset
{
    //@codingStandardsIgnoreEnd

    public function init()
    {
        parent::init();
        array_push($this->css, '/css/theme/dropup/bisque-red.css');
    }
}

来自数据库的菜单项

添加了一个辅助组件 buttflattery\multimenu\helpers\MenuHelper,如果您只想将数据库表中的所有菜单项添加到其中,并且让此组件生成菜单的 items 数组,则非常有用。

如果您还没有添加菜单表,您可以运行迁移并使用提供的 buttflattery\multimenu\models\Menu 模型。

运行迁移

在终端中运行以下命令以运行迁移

php ./yii migrate/up --migrationPath=@vendor/buttflattery/yii2-multimenu/src/migrations

+-----------+-------------+------+-----+---------+----------------+
| Field     | Type        | Null | Key | Default | Extra          |
+-----------+-------------+------+-----+---------+----------------+
| id        | int(11)     | NO   | PRI | NULL    | auto_increment |
| label     | varchar(50) | NO   |     | NULL    |                |
| link      | text        | YES  |     | NULL    |                |
| parent_id | int(11)     | YES  |     | NULL    |                |
+-----------+-------------+------+-----+---------+----------------+

配置 MenuHelper 组件

如果您使用的是 yii2-basic,则打开 config/web.php;如果您使用的是 advance-app,则打开 common/config/main.php,并在 components 数组下添加以下内容。

'components' => [
    'menuhelper' => [
        'class' => 'buttflattery\multimenu\helpers\MenuHelper',
        'model' => 'buttflattery\multimenu\models\Menu',
    ],

如果您希望使用自己的自定义模型并且已经有一个菜单表,您可以提供自己的模型命名空间,并适当地设置字段的名称,以便组件能够正确工作。以下为可以配置组件的完整选项集。

'components' => [
    'menuhelper' => [
        'class' => 'buttflattery\multimenu\helpers\MenuHelper',
        'model' => 'app\models\Menus',
        'linkField'=>'menu_link',
        'labelField'=>'menu_name',
        'idField'=>'menu_id',
        'parentIdField'=>'menu_parent_id',
    ],

在表中添加菜单项

当在数据库中添加菜单项时,请注意以下几点

  • 如果这是一个指向站点上的任何 controller/action 的链接,则提供类似 site/indexlink
  • 如果这是一个外部链接,则提供类似 https://example.comlink
  • 如果这是一个打开子菜单的父链接,则应将 url 设置为 #.,这将由 MenuHelper 替换为 javascript:void(0)
  • 如果您在 label 中有任何html,例如bootstrap 3中的 <hr /> 标签,可以用作分隔符 但您需要保持 url 字段为 NULL
  • 如果您希望在菜单内提供标题,则应在 label 字段中仅提供文本,并保持 url 字段为 NULL

请参阅下面的示例值

+----+------------------+------------------------------------------------+-----------+
| id | label            |      link                                      | parent_id |
+----+------------------+------------------------------------------------+-----------+
|  1 | Home             | site/index                                     |      NULL |
|  3 | Yii Filemanager  | https://plugins.idowstech.com/                 |      NULL |
|  4 | Yii2 Video Wall  | #.                                             |      NULL |
|  5 | Yii2 Form Wizard | #.                                             |      NULL |
|  6 | Carousel Mode    | #.                                             |         4 |
|  7 | Thumbnail Mode   | #.                                             |         4 |
|  8 | Playlist Mode    | #.                                             |         4 |
|  9 | Documentation    | #.                                             |         4 |
| 10 | Demos            | formwizard/index                               |         5 |
| 11 | Documentation    | formwizard/docs                                |         5 |
| 16 | Demo 3           | city/test?year=2015                            |         6 |
| 17 | Demo 4           | city/test?year=2015                            |         6 |
| 18 | Demo 5           | city/test?year=2015                            |         6 |
| 19 | Code Samples     | NULL                                           |         5 |
+----+------------------+------------------------------------------------+-----------+

现在您可以调用 function getMenuItems(orderByField) 来获取类似于下面的 $items 数组。

<?php
    use buttflattery\multimenu\MultiMenu;

    echo MultiMenu::widget(
        [
            'activeCssClass' => 'active',
            'items' => Yii::$app->menuhelper->getMenuItems(),
            'layoutTemplate' => '{multimenu}{brand}',
            'enableIcons'=>true,
            'brandUrl' => 'https://plugins.omaraslam.com',
            'brandLabel'=>'Yii2 Multimenu',
            'activateParents' => true,
            'multimenuOptions' => [
                'theme' => MultiMenu::THEME_BIGDROP,
            ],
        ]
    );

?>

可用的常量

  /**
  * For use with leftnav `position` option
  */
  const LEFT_NAV_FIXED = 'fixed';
  const LEFT_NAV_ABSOLUTE = 'absolute';
  const LEFT_NAV_DEFAULT = 'default';

  /**
   * Supported Transition effects by animate.css
   * https://daneden.github.io/animate.css/
  */
  const ANIMATE_BOUNCE_IN = 'bounceIn';
  const ANIMATE_BOUNCE_IN_DOWN = 'bounceInDown';
  const ANIMATE_BOUNCE_IN_UP = 'bounceInUp';
  const ANIMATE_BOUNCE_IN_LEFT = 'bounceInLeft';
  const ANIMATE_BOUNCE_IN_RIGHT = 'bounceInRight';

  const ANIMATE_FADE_IN = 'fadeIn';
  const ANIMATE_FADE_IN_DOWN = 'fadeInDown';
  const ANIMATE_FADE_IN_DOWN_BIG = 'fadeInDownBig';
  const ANIMATE_FADE_IN_LEFT = 'fadeInLeft';
  const ANIMATE_FADE_IN_LEFT_BIG = 'fadeInLeftBig';
  const ANIMATE_FADE_IN_RIGHT = 'fadeInRight';
  const ANIMATE_FADE_IN_RIGHT_BIG = 'fadeInRightBig';

  const ANIMATE_FLIP = 'flip';
  const ANIMATE_FLIP_IN_X = 'flipInX';
  const ANIMATE_FLIP_IN_Y = 'flipInY';

  const ANIMATE_LITE_SPEED_IN = 'lightSpeedIn';

  const ANIMATE_ROTATE_IN = 'rotateIn';
  const ANIMATE_ROTATE_IN_DOWN_LEFT = 'rotateInDownLeft';
  const ANIMATE_ROTATE_IN_DOWN_RIGHT = 'rotateInDownRight';
  const ANIMATE_ROTATE_IN_UP_LEFT = 'rotateInUpLeft';
  const ANIMATE_ROTATE_IN_UP_RIGHT = 'rotateInUpRight';

  const ANIMATE_SLIDE_IN_UP = 'slideInUp';
  const ANIMATE_SLIDE_IN_DOWN = 'slideInDown';
  const ANIMATE_SLIDE_IN_LEFT = 'slideInLeft';
  const ANIMATE_SLIDE_IN_RIGHT = 'slideInRight';

  const ANIMATE_ZOOM_IN = 'zoomIn';
  const ANIMATE_ZOOM_IN_UP = 'zoomInUp';
  const ANIMATE_ZOOM_IN_DOWN = 'zoomInDow';
  const ANIMATE_ZOOM_IN_LEFT = 'zoomInLeft';
  const ANIMATE_ZOOM_IN_RIGHT = 'zoomInRight';

  /**
   * delay types for `transitionDelay` option
   * under the menu specific options
   */
  const ANIMATE_DEFAULT = '';
  const ANIMATE_FAST = 'fast';
  const ANIMATE_FASTER = 'faster';
  const ANIMATE_SLOW = 'slow';
  const ANIMATE_SLOWER = 'slower';

  /**
   * Waves plugin effects http://fian.my.id/Waves/#examples
   * used for the option `wavesEffect`
   */
  const WAVES_TYPE_CIRCLE = 'waves-circle';
  const WAVES_TYPE_DEFAULT = 'default';

  const WAVES_LIGHT = 'waves-light';
  const WAVES_RED = 'waves-red';
  const WAVES_PINK = 'waves-pink';
  const WAVES_PURPLE = 'waves-purple';
  const WAVES_DEEP_PURPLE = 'waves-deep-purple';
  const WAVES_INDIGO = 'waves-indigo';
  const WAVES_BLUE = 'waves-blue';
  const WAVES_LIGHT_BLUE = 'waves-light-blue';
  const WAVES_CYAN = 'waves-cyan';
  const WAVES_TEAL = 'waves-teal';
  const WAVES_GREEN = 'waves-green';
  const WAVES_LIGHT_GREEN = 'waves-light-green';
  const WAVES_LIME = 'waves-lime';
  const WAVES_YELLOW = 'waves-yellow';
  const WAVES_AMBER = 'waves-amber';
  const WAVES_ORANGE = 'waves-orange';
  const WAVES_DEEP_ORANGE = 'waves-deep-orange';
  const WAVES_BROWN = 'waves-brown';
  const WAVES_GREY = 'waves-grey';
  const WAVES_BLUE_GREY = 'waves-blue-grey';
  const WAVES_BLACK = 'waves-black';

  /**
   * Themes available used for the `theme` option
   * under `multimenuOptions` option
   */
  const THEME_BIGDROP = 'bigdrop';
  const THEME_LEFTNAV = 'leftnav';
  const THEME_DROPUP = 'dropup';

我应该联系谁?