云客Drupal源码分析之导航菜单Navigation menus

菜单系统概述：
drupal8的菜单系统主要包含四大部分：导航菜单Navigation menus、本地任务Local tasks、本地动作Local actions、上下文链接Contextual links，都非常有用，本篇讲解第一部分：导航菜单，后简称菜单

菜单概述：
在讲述菜单前，需要先明确一些概念，菜单menu用于在网站中导航，是由菜单链接menu link组成的层次结构，也就是说一个菜单会包含0个或多个链接，是一个链接集，这些链接具备树型层次结构（父、子、兄弟），这个层次结构称为菜单树，菜单中的条目一定是链接，但反过来链接不一定是菜单，有时候会混淆“菜单”和 “菜单链接”，这需要根据语境上下文来判断，严格来讲“父菜单”这个说法是错误的，正确的说法是“父菜单链接”，因为在层次结构中讨论位置关系是指菜单内的菜单链接，而不是指菜单本身，没有父菜单一说，但生活中我们经常听到这样的讲法，约定俗成同时为了叙述简洁，本文并不排斥这种讲法，因此当遇到词语：父菜单、子菜单、兄弟菜单时，务必明白是指“父、子、兄弟菜单链接”，单独使用“菜单”一词时通常不是指一个菜单链接。

系统中可以有多个菜单以便用于不同地方的导航，因此每一个菜单都需要一个独一无二的名字，称为菜单名，系统默认提供的菜单及菜单名有：
   管理菜单（admin）：用于系统后台管理操作
   主导航菜单（main）：前台页面的主要导航菜单
   用户账户菜单（account）：用于登录后管理自己的账户
   页脚菜单（footer）：在前台页面显示一些导航链接

菜单不但需要菜单名，还需要描述、语言信息等，因此系统提供了一个配置实体来保存菜单信息，这就是菜单实体，有了菜单实体后，就可以向其添加菜单链接，实际上添加的菜单链接是在菜单实体之外单独保存，通过菜单名和菜单实体关联，添加菜单链接有三种方式：
静态定义：模块通过.links.menu.yml文件定义，是普通菜单链接
后台自定义：通过管理后台界面定义菜单链接，这样的菜单链接由实体支持，是实体菜单链接
程序方式定义：以上两种菜单链接都可以通过程序添加

菜单系统的实现涉及多个地方：
核心：提供基本功能（\core\lib\Drupal\Core\Menu）
系统system模块：提供菜单实体等（\Drupal\system\Entity\Menu）
菜单链接内容模块：提供菜单链接内容实体（\Drupal\menu_link_content\Entity\MenuLinkContent）等
菜单UI模块：提供系统后台用户操作接口（\core\modules\menu_ui）

在理解了菜单系统的整体结构后我们来看一下系统的具体实现。

菜单显示示例：
通常我们在区块配置中采用一个块来显示菜单，大多数时候应该这样使用，这里也给出程序方式显示一个菜单的示例：

        //取得菜单链接树对象，这是使用入口
        $menu_tree = \Drupal::service('menu.link_tree');
        //准备菜单树参数
        $parameters = new \Drupal\Core\Menu\MenuTreeParameters();
        $parameters->setMinDepth(2)->setMaxDepth(5)->onlyEnabledLinks();
        //按菜单名加载菜单树 这里我们加载管理菜单
        $tree = $menu_tree->load('admin', $parameters);
        //准备菜单树操纵器，操纵器用于修改菜单树
        $manipulators = [
            ['callable' => 'menu.default_tree_manipulators:checkAccess'], //权限检查
            ['callable' => 'menu.default_tree_manipulators:generateIndexAndSort'], //菜单排序
        ];
        //运用操纵器
        $tree = $menu_tree->transform($tree, $manipulators);
        //返回显示菜单树的渲染数组
        $element['menu'] = $menu_tree->build($tree);
        return $element;

请在控制器中运行以上代码，接下来讲解其原理和各组件

菜单链接插件管理器：
用于收集yml文件定义的菜单链接，添加、加载、移除菜单链接等，系统将yml文件定义的菜单链接视为插件，因此这是一个插件管理器，定义如下：
服务id：plugin.manager.menu.link
类：Drupal\Core\Menu\MenuLinkManager
使用Yaml发现机制（详见本系列插件下集），查找模块根目录下的“模块名.links.menu.yml”文件，以该文件内的根键做插件id（也是菜单链接id），对应数组做插件定义，这称为菜单链接的静态定义，该定义数组有如下键：
menu_name：菜单名，默认值“tools”，可选，如没有提供则子菜单自动继承父菜单的值（如果指定了但和父菜单不同，将以父菜单值为准），如果是顶级菜单链接往往需要指定，这样才能将菜单链接树和菜单实体相关联，如顶级菜单链接没有指定，将使用默认值，菜单名在菜单UI模块中被限制为只能使用小写字母、数字、连字符
route_name：路由名，字符串值，默认为空字符串，和url二选一必填
route_parameters：路由参数，数组值，默认为空数组 []，可选
url：外部url，默认为空字符串，和路由名二选一必填
title：菜单标题，字符串值，被系统理解为可翻译的，在系统内部被转化为翻译对象TranslatableMarkup，用于html链接标签的文本，并非title属性值
title_context：可选，标题翻译上下文，见翻译系统
description：菜单描述，同标题，可用于html链接标签的title属性
description_context：可选，描述