vue3-element-admin 菜单管理实现：树形结构与权限控制

2026-02-05 05:17:38作者：柯茵沙

一、菜单管理痛点与解决方案

你是否在开发后台管理系统时遇到过这些问题：多级菜单渲染异常、权限控制与菜单展示脱节、不同用户看到相同菜单结构？vue3-element-admin 作为基于 Vue3 + Element-Plus 的企业级前端框架，提供了完整的菜单管理解决方案。本文将从数据结构设计、树形组件实现、权限动态过滤三个维度，详解如何构建灵活可控的菜单系统。

读完本文你将掌握：

菜单树形结构的前后端数据交互设计
Element-Plus 树形组件与菜单数据的绑定技巧
基于权限标识的菜单动态过滤实现
菜单管理的增删改查完整业务流程

二、菜单数据模型设计

2.1 核心数据结构

菜单系统的核心在于数据模型设计，vue3-element-admin 采用以下数据结构描述菜单：

// 菜单视图对象 (MenuVO)
export interface MenuVO {
  id?: string;                // 菜单ID
  name?: string;              // 菜单名称
  parentId?: string;          // 父菜单ID
  type?: MenuTypeEnum;        // 菜单类型
  routePath?: string;         // 路由路径
  component?: string;         // 组件路径
  perm?: string;              // 权限标识
  visible?: number;           // 是否可见(1:显示;0:隐藏)
  sort?: number;              // 排序
  icon?: string;              // 图标
  children?: MenuVO[];        // 子菜单
}

// 菜单类型枚举
export enum MenuTypeEnum {
  CATALOG = "CATALOG",  // 目录
  MENU = "MENU",        // 菜单
  BUTTON = "BUTTON",    // 按钮
  EXTLINK = "EXTLINK"   // 外链
}

2.2 树形关系表达

菜单的层级关系通过 parentId 和 children 字段共同维护：

顶级菜单 parentId 为 "0"
子菜单通过 parentId 关联父菜单
前端展示时通过 children 字段形成树形结构

这种设计既便于数据库存储（扁平化结构），又便于前端渲染（嵌套结构）。

三、菜单管理 API 设计

vue3-element-admin 封装了完整的菜单管理 API，位于 src/api/system/menu-api.ts：

const MenuAPI = {
  /** 获取当前用户的路由列表 */
  getRoutes() {
    return request<any, RouteVO[]>({ url: "/api/v1/menus/routes", method: "get" });
  },
  
  /** 获取菜单树形列表 */
  getList(queryParams: MenuQuery) {
    return request<any, MenuVO[]>({ url: "/api/v1/menus", method: "get", params: queryParams });
  },
  
  /** 获取菜单表单数据 */
  getFormData(id: string) {
    return request<any, MenuForm>({ url: `/api/v1/menus/${id}/form`, method: "get" });
  },
  
  /** 新增菜单 */
  create(data: MenuForm) {
    return request({ url: "/api/v1/menus", method: "post", data });
  },
  
  /** 修改菜单 */
  update(id: string, data: MenuForm) {
    return request({ url: `/api/v1/menus/${id}`, method: "put", data });
  },
  
  /** 删除菜单 */
  deleteById(id: string) {
    return request({ url: `/api/v1/menus/${id}`, method: "delete" });
  },
};

主要 API 功能说明：

API 方法	功能描述	前端应用场景
getRoutes	获取当前用户可访问的路由	登录后构建路由系统
getList	获取菜单树形列表	菜单管理页面数据展示
getFormData	获取菜单详情	编辑菜单时加载表单数据
create/update	新增/修改菜单	菜单管理页面表单提交
deleteById	删除菜单	菜单管理页面删除操作

四、树形菜单实现

4.1 Element-Plus 树形表格

菜单管理页面使用 Element-Plus 的树形表格组件展示菜单层级关系，核心代码如下：

<el-table
  ref="dataTableRef"
  v-loading="loading"
  row-key="id"
  :data="menuTableData"
  :tree-props="{
    children: 'children',
    hasChildren: 'hasChildren',
  }"
  class="data-table__content"
>
  <el-table-column label="菜单名称" min-width="200">
    <template #default="scope">
      <!-- 图标渲染 -->
      <template v-if="scope.row.icon && scope.row.icon.startsWith('el-icon')">
        <el-icon style="vertical-align: -0.15em">
          <component :is="scope.row.icon.replace('el-icon-', '')" />
        </el-icon>
      </template>
      <!-- 菜单名称 -->
      {{ scope.row.name }}
    </template>
  </el-table-column>
  
  <el-table-column label="类型" align="center" width="80">
    <template #default="scope">
      <el-tag v-if="scope.row.type === MenuTypeEnum.CATALOG" type="warning">目录</el-tag>
      <el-tag v-if="scope.row.type === MenuTypeEnum.MENU" type="success">菜单</el-tag>
      <el-tag v-if="scope.row.type === MenuTypeEnum.BUTTON" type="danger">按钮</el-tag>
      <el-tag v-if="scope.row.type === MenuTypeEnum.EXTLINK" type="info">外链</el-tag>
    </template>
  </el-table-column>
  
  <!-- 其他列... -->
</el-table>

关键属性说明：

row-key="id": 必须指定唯一键，确保树形结构正确渲染
:tree-props: 配置树形属性，children 指定子节点字段名
类型标签通过 el-tag 组件实现不同类型菜单的视觉区分

4.2 菜单数据加载流程

菜单数据加载的生命周期如下：

sequenceDiagram
  participant 页面组件
  participant MenuAPI
  participant 后端服务
  participant 表格组件
  
  页面组件->>页面组件: onMounted()
  页面组件->>MenuAPI: 调用 getList()
  MenuAPI->>后端服务: 发送 GET 请求
  后端服务-->>MenuAPI: 返回 MenuVO[] 数组
  MenuAPI-->>页面组件: 接收菜单数据
  页面组件->>表格组件: 绑定 menuTableData
  表格组件->>表格组件: 渲染树形结构

核心代码实现：

// 菜单表格数据
const menuTableData = ref<MenuVO[]>([]);
// 加载状态
const loading = ref(false);

// 查询菜单
function handleQuery() {
  loading.value = true;
  MenuAPI.getList(queryParams)
    .then((data) => {
      menuTableData.value = data;  // 直接赋值树形数据
    })
    .finally(() => {
      loading.value = false;
    });
}

// 页面挂载时加载数据
onMounted(() => {
  handleQuery();
});

五、菜单权限控制实现

5.1 权限控制核心原理

vue3-element-admin 的菜单权限控制基于"权限标识(perm)"实现，采用以下流程：

flowchart TD
    A[用户登录] --> B[获取用户权限列表]
    B --> C[获取完整菜单树]
    C --> D[根据权限过滤菜单]
    D --> E[生成路由配置]
    E --> F[渲染菜单组件]

5.2 权限标识设计

权限标识采用"模块:资源:操作"的三段式命名规范，例如：

权限标识	含义说明
sys:menu:add	系统管理-菜单管理-新增操作
sys:menu:edit	系统管理-菜单管理-编辑操作
sys:menu:delete	系统管理-菜单管理-删除操作

5.3 权限指令实现

通过自定义指令 v-hasPerm 实现按钮级别的权限控制：

// directive/permission/index.ts
import type { Directive } from 'vue';

export const hasPerm: Directive = {
  mounted(el, binding) {
    const { value } = binding;
    const permissions = useUserStore().permissions;
    
    if (value && value instanceof Array && value.length > 0) {
      const hasPermission = permissions.some(perm => value.includes(perm));
      if (!hasPermission) {
        el.parentNode?.removeChild(el);
      }
    }
  }
};

在菜单管理页面中使用：

<el-button
  v-hasPerm="['sys:menu:add']"
  type="success"
  icon="plus"
  @click="handleOpenDialog('0')"
>
  新增
</el-button>

5.4 菜单动态过滤

路由级别权限过滤在 src/plugins/permission.ts 中实现：

// 过滤无权访问的菜单
function filterAsyncRoutes(routes: RouteVO[], permissions: string[]): RouteVO[] {
  const res: RouteVO[] = [];
  
  routes.forEach(route => {
    const tmp = { ...route };
    
    // 检查菜单权限
    if (hasPermission(tmp, permissions)) {
      if (tmp.children) {
        tmp.children = filterAsyncRoutes(tmp.children, permissions);
      }
      res.push(tmp);
    }
  });
  
  return res;
}

// 判断是否有权限访问菜单
function hasPermission(route: RouteVO, permissions: string[]): boolean {
  // 无需权限的菜单直接放行
  if (!route.meta?.perm) return true;
  
  // 检查是否拥有菜单所需权限
  return permissions.includes(route.meta.perm);
}

六、菜单管理操作流程

6.1 新增菜单流程

新增菜单通过抽屉组件实现表单提交，关键步骤：

选择父菜单：通过树形选择器选择菜单层级

<el-tree-select
  v-model="formData.parentId"
  placeholder="选择上级菜单"
  :data="menuOptions"
  filterable
  check-strictly
/>

选择菜单类型：根据不同类型动态显示表单字段

<el-radio-group v-model="formData.type" @change="handleMenuTypeChange">
  <el-radio :value="MenuTypeEnum.CATALOG">目录</el-radio>
  <el-radio :value="MenuTypeEnum.MENU">菜单</el-radio>
  <el-radio :value="MenuTypeEnum.BUTTON">按钮</el-radio>
  <el-radio :value="MenuTypeEnum.EXTLINK">外链</el-radio>
</el-radio-group>

动态表单控制：根据菜单类型显示不同表单项

// 菜单类型切换处理
function handleMenuTypeChange() {
  if (formData.value.type === MenuTypeEnum.MENU) {
    // 菜单类型需要路由名称和组件路径
    formData.value.routeName = '';
    formData.value.component = '';
  } else if (formData.value.type === MenuTypeEnum.BUTTON) {
    // 按钮类型需要权限标识
    formData.value.perm = '';
  }
}

6.2 菜单编辑与删除

编辑菜单时通过菜单ID加载表单数据：

function handleOpenDialog(parentId?: string, menuId?: string) {
  if (menuId) {
    dialog.title = "编辑菜单";
    MenuAPI.getFormData(menuId).then((data) => {
      formData.value = data;  // 加载菜单详情
    });
  } else {
    dialog.title = "新增菜单";
    formData.value.parentId = parentId?.toString();  // 设置父菜单ID
  }
}

删除菜单需要处理子菜单存在的情况：

function handleDelete(menuId: string) {
  ElMessageBox.confirm("确认删除已选中的数据项?", "警告", {
    confirmButtonText: "确定",
    cancelButtonText: "取消",
    type: "warning",
  }).then(() => {
    MenuAPI.deleteById(menuId).then(() => {
      ElMessage.success("删除成功");
      handleQuery();  // 重新加载菜单列表
    });
  });
}

七、高级特性实现

7.1 菜单图标选择器

菜单图标选择通过自定义组件 IconSelect 实现，支持 Element-Plus 图标和自定义 SVG 图标：

<icon-select v-model="formData.icon" />

7.2 路由参数配置

菜单支持配置路由参数，用于页面跳转时传递额外参数：

<div v-for="(item, index) in formData.params" :key="index">
  <el-input v-model="item.key" placeholder="参数名" />
  <span class="mx-1">=</span>
  <el-input v-model="item.value" placeholder="参数值" />
  <el-icon @click="addParam">+</el-icon>
  <el-icon @click="removeParam(index)">-</el-icon>
</div>

7.3 菜单缓存控制

通过 keepAlive 字段控制页面缓存：

<el-radio-group v-model="formData.keepAlive">
  <el-radio :value="1">开启</el-radio>
  <el-radio :value="0">关闭</el-radio>
</el-radio-group>

实现原理是在路由元信息中设置 keepAlive 属性，配合 <keep-alive> 组件缓存页面：

<router-view v-slot="{ Component }">
  <keep-alive>
    <component :is="Component" v-if="$route.meta.keepAlive" />
  </keep-alive>
  <component :is="Component" v-else />
</router-view>

八、总结与最佳实践

8.1 开发建议

权限设计：遵循最小权限原则，为不同角色分配精确的菜单权限标识
菜单层级：建议菜单层级不超过3级，避免过深的层级影响用户体验
性能优化：菜单数据量大时考虑分页加载和虚拟滚动
缓存策略：合理设置 keepAlive，频繁切换的页面建议开启缓存

8.2 常见问题解决方案

问题	解决方案
菜单不显示	检查权限标识是否正确、路由配置是否有误
树形结构异常	确保 `row-key` 唯一且 `children` 字段正确
路由跳转404	检查 `routePath` 和 `component` 路径是否匹配
权限控制失效	检查 `v-hasPerm` 指令和权限列表是否同步