Vue3+Element-Plus实现生产级侧边栏菜单：折叠动画、状态持久化与移动端适配

1. 项目背景与核心价值

最近在重构一个后台管理系统，从Vue2 + Element UI 迁移到 Vue3 + Element-Plus。迁移过程中，一个看似基础但体验至关重要的功能——左侧菜单的折叠与展开，让我重新审视了一遍。很多新手，甚至一些有经验的开发者，在实现这个功能时，往往只停留在“点击按钮，菜单宽度变化”的层面，却忽略了动画流畅性、状态持久化、路由激活匹配、以及移动端适配等一系列影响用户体验的细节。网上很多教程也止步于基础实现，导致大家做出来的菜单交互生硬，状态混乱。

这次，我就结合Vue3的组合式API和Element-Plus的最新组件，来完整地拆解一个生产级可用的左侧菜单折叠展开功能。这不仅仅是“二七”（可以理解为第二十七次迭代或一个版本代号），更是一次对细节的深度打磨。我们将覆盖从基础布局、状态管理、平滑动画，到持久化、响应式以及那些容易踩坑的边界情况处理。无论你是刚刚接触Vue3，还是正在寻找一个更优雅的菜单解决方案，相信这篇内容都能给你带来直接的参考价值。

2. 技术栈选型与项目初始化考量

在开始动手之前，明确我们的技术栈和项目起点至关重要。标题已经指明了是 Vue3 和 Element-Plus，这几乎是当前Vue中后台项目的标准搭配。但为什么是它们，以及初始化时要注意什么，这里有几个关键点。

2.1 为什么是Vue3 + Element-Plus？

首先，Vue3 带来的组合式 API (Composition API)是核心优势。对于菜单组件这种自身带有复杂内部状态（折叠状态、激活路径、打开的子菜单等）的模块，使用setup语法和ref、computed、watch等函数来组织逻辑，比 Vue2 的 Options API 更加清晰和灵活。状态和逻辑可以按功能聚合，而不是分散在data、methods、watch等选项中。

其次，Element-Plus 是对 Element UI 的 Vue3 版本升级。它提供了<el-menu>组件，原生支持垂直模式、手风琴模式、路由集成等，是我们实现菜单功能的基础。选择它，意味着我们不需要从零开始编写菜单的样式和基础交互，可以专注于业务逻辑和体验增强。

2.2 项目创建与依赖安装

假设你已经有一个基于 Vite 创建的 Vue3 项目（这是目前最推荐的方式）。如果没有，可以通过以下命令快速创建一个：

npm create vue@latest my-admin-project # 按照提示选择需要的特性，通常需要加入 TypeScript 和 Vue Router。

然后，进入项目目录，安装 Element-Plus 和图标库（菜单常需要图标）：

cd my-admin-project npm install element-plus @element-plus/icons-vue

接下来是引入 Element-Plus。对于后台管理系统，我推荐使用完整引入，虽然体积稍大，但省去了按需引入的配置麻烦，开发体验更流畅。在main.ts或main.js中：

import { createApp } from 'vue' import App from './App.vue' import router from './router' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' import * as ElementPlusIconsVue from '@element-plus/icons-vue' const app = createApp(App) // 注册所有图标组件 for (const [key, component] of Object.entries(ElementPlusIconsVue)) { app.component(key, component) } app.use(router) app.use(ElementPlus) app.mount('#app')

注意：图标注册这一步很重要。Element-Plus 将图标作为独立的组件提供，我们需要全局注册后才能直接在模板中使用<el-icon>。

至此，基础环境就准备好了。我们的工作将主要集中在一个布局组件（如Layout.vue）和菜单组件（如SidebarMenu.vue）中。

3. 基础布局构建与菜单组件集成

一个典型的后台管理布局包含顶部导航栏、左侧菜单栏、主内容区。这里我们使用 Element-Plus 的<el-container>系列组件来快速搭建骨架。

3.1 使用 ElContainer 构建页面骨架

在Layout.vue中，我们先搭建一个基础的响应式布局容器。

<!-- Layout.vue --> <template> <el-container class="layout-container"> <!-- 左侧侧边栏，其宽度将受折叠状态控制 --> <el-aside :width="asideWidth" class="layout-aside"> <SidebarMenu :is-collapse="isCollapse" /> </el-aside> <el-container> <!-- 顶部Header，放置折叠按钮和用户信息等 --> <el-header class="layout-header"> <div class="header-left"> <!-- 折叠/展开触发按钮 --> <el-button :icon="isCollapse ? Expand : Fold" circle plain @click="toggleCollapse" /> <span class="system-title">后台管理系统</span> </div> <div class="header-right">...</div> </el-header> <!-- 主内容区，使用 el-main 确保内边距和滚动 --> <el-main class="layout-main"> <router-view v-slot="{ Component }"> <transition name="fade-transform" mode="out-in"> <component :is="Component" /> </transition> </router-view> </el-main> </el-container> </el-container> </template> <script setup lang="ts"> import { ref, computed } from 'vue' import { Fold, Expand } from '@element-plus/icons-vue' import SidebarMenu from './SidebarMenu.vue' // 控制折叠状态的核心响应式变量 const isCollapse = ref(false) // 根据折叠状态动态计算侧边栏宽度 const asideWidth = computed(() => (isCollapse.value ? '64px' : '200px')) // 切换折叠状态的函数 const toggleCollapse = () => { isCollapse.value = !isCollapse.value } </script> <style scoped lang="scss"> .layout-container { height: 100vh; .layout-aside { background-color: #304156; transition: width 0.3s ease-in-out; // 侧边栏宽度过渡动画 overflow: hidden; // 防止菜单内容在收缩时溢出 } .layout-header { display: flex; align-items: center; justify-content: space-between; border-bottom: 1px solid #e6e6e6; background-color: #fff; .header-left { display: flex; align-items: center; gap: 16px; } } .layout-main { background-color: #f0f2f5; padding: 20px; } } </style>

这里有几个关键设计点：

1. 状态驱动：isCollapse是一个布尔类型的ref，它是整个菜单折叠状态的核心。它同时控制着侧边栏宽度 (asideWidth) 和按钮图标。
2. 计算属性：asideWidth是一个计算属性，它根据isCollapse的值返回'64px'（折叠）或'200px'（展开）。这样就将状态与样式解耦了。
3. CSS过渡：在.layout-aside的样式中，我们为width属性添加了transition: width 0.3s ease-in-out;。这是实现平滑折叠动画的关键。当asideWidth变化时，浏览器会自动应用这个过渡效果。

3.2 实现 SidebarMenu 菜单组件

现在我们来创建SidebarMenu.vue组件，它接收isCollapse属性，并渲染实际的导航菜单。

<!-- SidebarMenu.vue --> <template> <el-menu :default-active="activeMenu" :collapse="isCollapse" :collapse-transition="false" background-color="#304156" text-color="#bfcbd9" active-text-color="#409eff" unique-opened router class="sidebar-menu" > <menu-item v-for="route in menuRoutes" :key="route.path" :item="route" /> </el-menu> </template> <script setup lang="ts"> import { computed } from 'vue' import { useRoute } from 'vue-router' import MenuItem from './MenuItem.vue' // 定义组件接收的属性 interface Props { isCollapse: boolean } defineProps<Props>() const route = useRoute() // 计算当前激活的菜单项，用于高亮 const activeMenu = computed(() => route.path) // 模拟从后端或路由配置中获取的菜单数据 const menuRoutes = [ { path: '/dashboard', meta: { title: '仪表盘', icon: 'Odometer' }, }, { path: '/user', meta: { title: '用户管理', icon: 'User' }, children: [ { path: '/user/list', meta: { title: '用户列表' } }, { path: '/user/role', meta: { title: '角色管理' } }, ], }, { path: '/system', meta: { title: '系统管理', icon: 'Setting' }, children: [ { path: '/system/menu', meta: { title: '菜单管理' } }, { path: '/system/log', meta: { title: '操作日志' } }, ], }, ] </script> <style scoped lang="scss"> .sidebar-menu { border-right: none; // 去除默认边框 height: 100%; // 当菜单折叠时，让文字隐藏得更优雅，而不是突然消失 :deep(.el-menu-item), :deep(.el-sub-menu__title) { span { transition: opacity 0.2s; opacity: 1; } } // 折叠状态下，隐藏菜单项文字 :deep(.el-menu--collapse) { .el-menu-item, .el-sub-menu__title { span { opacity: 0; width: 0; overflow: hidden; } } } } </style>

核心属性解析：

• :collapse="isCollapse"：这是 Element-Plus<el-menu>接收折叠状态的核心属性。设置为true时，菜单会收起为仅图标模式。
• :collapse-transition="false"：禁用 Element-Plus 自带的折叠动画。因为我们已经在容器层面 (el-aside) 控制了宽度过渡，禁用内置动画可以避免两者冲突，使效果更平滑。
• router：启用此属性后，将index（每个菜单项的path）作为路由路径进行导航。这是实现点击菜单跳转页面的关键。
• unique-opened：是否只保持一个子菜单展开（手风琴模式）。在后台管理中通常开启，避免页面过于杂乱。
• :default-active="activeMenu"：设置当前激活菜单的高亮。我们通过useRoute()获取当前路由路径，并用计算属性activeMenu动态绑定，确保页面刷新或通过URL进入时，菜单高亮状态正确。

3.3 实现递归菜单项组件 MenuItem

为了处理嵌套的多级菜单，我们需要一个递归组件MenuItem.vue。

<!-- MenuItem.vue --> <template> <!-- 如果没有子路由，渲染 el-menu-item --> <el-menu-item v-if="!hasChildren" :index="item.path"> <el-icon v-if="item.meta?.icon"> <component :is="item.meta.icon" /> </el-icon> <template #title>{{ item.meta?.title }}</template> </el-menu-item> <!-- 如果有子路由，渲染 el-sub-menu --> <el-sub-menu v-else :index="item.path"> <template #title> <el-icon v-if="item.meta?.icon"> <component :is="item.meta.icon" /> </el-icon> <span>{{ item.meta?.title }}</span> </template> <!-- 递归调用自身，渲染子菜单 --> <menu-item v-for="child in item.children" :key="child.path" :item="child" /> </el-sub-menu> </template> <script setup lang="ts"> import type { RouteRecordRaw } from 'vue-router' interface MenuItem { path: string meta?: { title: string icon?: string } children?: MenuItem[] } interface Props { item: MenuItem } defineProps<Props>() // 判断当前菜单项是否有子项（用于路由导航） const hasChildren = (item: MenuItem) => { // 这里有一个关键判断：如果子项只有一个，且该子项的 path 等于父项的 path？ // 通常，我们判断是否有需要展示的子菜单项。 // 一种常见情况：父路由本身只是一个布局容器，不用于导航，其 `redirect` 到了第一个子路由。 // 在我们的简单数据结构里，直接判断 children 是否存在且长度大于0。 return item.children && item.children.length > 0 } </script>

这个递归组件是菜单渲染的核心。它根据传入的item数据，判断是否有children，从而决定渲染为叶子节点 (el-menu-item) 还是父节点 (el-sub-menu)。对于父节点，在其插槽内递归调用自身，直至渲染完所有层级。

至此，一个基础的、带有折叠展开功能的菜单就完成了。点击顶部按钮，可以看到侧边栏平滑地收起和展开。但这仅仅是开始，接下来我们要解决一系列实际开发中会遇到的“坑”。

4. 状态持久化：让折叠状态记住用户的选择

想象一下，用户习惯折叠菜单以获得更大的工作区，当他刷新页面或重新打开浏览器时，菜单又恢复了展开状态，体验非常割裂。因此，我们需要将isCollapse状态持久化到本地存储（LocalStorage）中。

我们将在Layout.vue中实现这个功能。这里介绍两种方式：基础方式和组合式函数封装。

4.1 基础实现：直接使用 localStorage

<!-- 在 Layout.vue 的 script setup 部分修改 --> <script setup lang="ts"> import { ref, computed, onMounted } from 'vue' import { Fold, Expand } from '@element-plus/icons-vue' import SidebarMenu from './SidebarMenu.vue' // 从 localStorage 读取初始状态，如果没有则默认为 false (展开) const getDefaultCollapse = (): boolean => { const saved = localStorage.getItem('app-sidebar-collapse') return saved ? JSON.parse(saved) : false } const isCollapse = ref(getDefaultCollapse()) // 切换状态时，同步保存到 localStorage const toggleCollapse = () => { isCollapse.value = !isCollapse.value localStorage.setItem('app-sidebar-collapse', JSON.stringify(isCollapse.value)) } const asideWidth = computed(() => (isCollapse.value ? '64px' : '200px')) // 可选：在组件挂载时，也可以根据浏览器宽度初始化状态（响应式设计） onMounted(() => { // 例如，在小屏幕设备上默认折叠 // if (window.innerWidth < 768) { // isCollapse.value = true // localStorage.setItem('app-sidebar-collapse', 'true') // } }) </script>

这种方式简单直接，但状态管理逻辑和组件逻辑耦合在一起。如果其他组件也需要使用持久化状态，代码就会重复。

4.2 进阶实现：封装 useLocalStorage 组合式函数

更好的做法是封装一个可复用的组合式函数useLocalStorage。

// composables/useLocalStorage.ts import { ref, watch } from 'vue' export function useLocalStorage<T>(key: string, defaultValue: T) { // 创建响应式数据，初始值从 localStorage 读取 const data = ref<T>(() => { const item = localStorage.getItem(key) try { return item ? JSON.parse(item) : defaultValue } catch { return defaultValue } }) // 监听 data 变化，自动同步到 localStorage watch( data, (newVal) => { localStorage.setItem(key, JSON.stringify(newVal)) }, { deep: true } // 如果 T 是对象，需要深度监听 ) return data }

然后在Layout.vue中使用它：

<script setup lang="ts"> import { ref, computed } from 'vue' import { Fold, Expand } from '@element-plus/icons-vue' import SidebarMenu from './SidebarMenu.vue' import { useLocalStorage } from '@/composables/useLocalStorage' // 使用组合式函数，代码非常简洁 const isCollapse = useLocalStorage<boolean>('app-sidebar-collapse', false) const toggleCollapse = () => { isCollapse.value = !isCollapse.value // 注意：状态保存已由 useLocalStorage 内部的 watch 自动完成 } const asideWidth = computed(() => (isCollapse.value ? '64px' : '200px')) </script>

这种方式将状态持久化的逻辑抽象出来，使得组件代码更加清晰，也易于测试和复用。useLocalStorage返回的也是一个ref，你可以像操作普通响应式数据一样操作它，所有变更都会自动保存。

实操心得：对于简单的布尔值或字符串，基础方式够用。但对于稍复杂的项目，强烈建议采用组合式函数封装。这不仅是为了代码复用，更是为了践行 Vue3 组合式 API 的设计思想——将相关的逻辑关注点组合在一起。此外，考虑到localStorage是同步操作且可能抛出异常（如用户禁用），在生产环境中，最好将其包裹在try...catch中，上述封装已简单处理。

5. 响应式设计与移动端适配

一个现代化的后台管理系统必须在不同屏幕尺寸下都有良好的表现。我们的菜单在桌面端可以自由折叠展开，但在移动端（小屏幕）下，通常需要自动折叠，并且可能以抽屉（Drawer）的形式出现。

5.1 基于 CSS Media Query 的初步适配

首先，我们可以通过 CSS 媒体查询，在小屏幕下强制修改一些样式。

// 在 Layout.vue 的 style 部分添加 @media screen and (max-width: 768px) { .layout-container { .layout-aside { // 在移动端，侧边栏通常以抽屉形式覆盖在内容上，而不是并排 // 我们先将其隐藏，通过一个按钮触发显示 position: fixed !important; left: 0; top: 0; z-index: 2001; height: 100vh; // 初始状态是隐藏的（移出屏幕） transform: translateX(-100%); // 展开状态 &.is-mobile-open { transform: translateX(0); } // 移除宽度过渡，改用 transform 过渡，性能更好 transition: transform 0.3s ease-in-out; width: 200px !important; // 移动端抽屉有固定宽度 } // 当侧边栏打开时，为主内容区添加一个遮罩层 .layout-mask { position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; background-color: rgba(0, 0, 0, 0.5); z-index: 2000; } } }

这段 CSS 做了几件事：

1. 在屏幕宽度小于 768px 时，将侧边栏改为固定定位（position: fixed），使其脱离文档流。
2. 默认使用transform: translateX(-100%)将其隐藏在屏幕左侧。
3. 定义一个is-mobile-open类，当此类被添加时，侧边栏滑入 (transform: translateX(0))。
4. 将过渡效果从width改为transform，因为transform的动画性能通常更好。
5. 固定了移动端侧边栏的宽度为200px。

5.2 使用 Vue 响应式状态管理移动端逻辑

CSS 只处理了样式，我们还需要用 Vue 来管理移动端的打开/关闭状态。修改Layout.vue：

<template> <el-container class="layout-container"> <!-- 移动端遮罩层 --> <div v-if="isMobile && mobileSidebarOpen" class="layout-mask" @click="closeMobileSidebar" ></div> <!-- 侧边栏：添加移动端状态类 --> <el-aside :width="asideWidth" :class="['layout-aside', { 'is-mobile-open': mobileSidebarOpen }]" > <SidebarMenu :is-collapse="isCollapse" /> </el-aside> <el-container> <el-header class="layout-header"> <div class="header-left"> <!-- 移动端下，按钮功能变为打开/关闭抽屉 --> <el-button v-if="!isMobile" :icon="isCollapse ? Expand : Fold" circle plain @click="toggleCollapse" /> <el-button v-else icon="Menu" circle plain @click="openMobileSidebar" /> <span class="system-title">后台管理系统</span> </div> </el-header> <el-main class="layout-main"> <router-view v-slot="{ Component }"> <transition name="fade-transform" mode="out-in"> <component :is="Component" /> </transition> </router-view> </el-main> </el-container> </el-container> </template> <script setup lang="ts"> import { ref, computed, onMounted, onUnmounted } from 'vue' import { Fold, Expand, Menu } from '@element-plus/icons-vue' import SidebarMenu from './SidebarMenu.vue' import { useLocalStorage } from '@/composables/useLocalStorage' const isCollapse = useLocalStorage<boolean>('app-sidebar-collapse', false) // 响应式判断是否为移动端 const isMobile = ref(false) // 控制移动端侧边栏抽屉的开关 const mobileSidebarOpen = ref(false) // 检查屏幕宽度并更新 isMobile 状态 const checkIsMobile = () => { isMobile.value = window.innerWidth < 768 // 如果是移动端，且侧边栏是展开状态，则自动折叠并关闭抽屉 if (isMobile.value) { isCollapse.value = false // 移动端下，菜单内部不应用折叠样式（因为整个抽屉都是展开的） mobileSidebarOpen.value = false } } // 切换桌面端折叠状态 const toggleCollapse = () => { if (isMobile.value) return // 移动端不执行此逻辑 isCollapse.value = !isCollapse.value } // 打开移动端侧边栏抽屉 const openMobileSidebar = () => { mobileSidebarOpen.value = true } // 关闭移动端侧边栏抽屉 const closeMobileSidebar = () => { mobileSidebarOpen.value = false } // 计算属性：桌面端根据 isCollapse 计算宽度，移动端返回固定宽度（由CSS控制） const asideWidth = computed(() => { if (isMobile.value) { return '200px' // 移动端抽屉固定宽度，实际显示由CSS的transform控制 } return isCollapse.value ? '64px' : '200px' }) // 生命周期：初始化及监听窗口变化 onMounted(() => { checkIsMobile() window.addEventListener('resize', checkIsMobile) }) onUnmounted(() => { window.removeEventListener('resize', checkIsMobile) }) </script>

逻辑解析：

1. isMobile：通过监听window.resize事件，动态判断当前是否处于移动端（宽度<768px）。
2. mobileSidebarOpen：专门控制移动端抽屉的开关状态，与桌面端的isCollapse状态分离。
3. 条件渲染与样式绑定：
   • 在移动端 (v-if="isMobile")，显示一个遮罩层 (layout-mask)，点击可关闭抽屉。
   • 侧边栏通过:class绑定is-mobile-open类，控制其滑入滑出。
   • 顶部按钮根据isMobile显示不同的图标和绑定不同的事件：桌面端是折叠/展开图标，移动端是“汉堡菜单”图标，用于打开抽屉。
4. 状态隔离：在移动端，我们强制将isCollapse设为false，因为移动端的折叠逻辑是“整个抽屉的显示与隐藏”，而不是“菜单内部的收起展开”。这样保证了<el-menu>组件在移动端抽屉内总是以完整形式展示。

踩坑提醒：这里有一个常见的冲突点。Element-Plus 的<el-menu>在collapse状态下，会改变子菜单的弹出方式（从内联变为浮层）。在移动端抽屉中，如果菜单是折叠状态，子菜单会以浮层形式弹出，可能会被抽屉的边界裁剪或位置错乱。因此，我们在移动端将isCollapse设为false是必要的，确保子菜单在抽屉内正常展开。同时，在SidebarMenu.vue中，我们传参时也要注意：<SidebarMenu :is-collapse="isMobile ? false : isCollapse" />是更严谨的写法。

6. 路由激活与菜单高亮的深度处理

菜单高亮是导航的核心反馈。虽然我们通过:default-active="route.path"进行了基本绑定，但在实际项目中，路由结构往往更复杂，直接使用route.path可能会高亮失败。

6.1 问题场景分析

1. 嵌套路由：你的路由配置可能是嵌套的，例如/system/user对应一个嵌套的<router-view>。但你的菜单项可能只定义到了/system。此时，需要高亮的是/system这个父级菜单。
2. 动态路由：路径中包含参数，如/user/edit/123。你的菜单项路径是/user。你需要匹配到/user并高亮它。
3. 重定向路由：你访问/，被重定向到/dashboard。此时需要高亮的是/dashboard对应的菜单。

6.2 实现一个健壮的 activeMenu 计算属性

我们需要一个函数，能够根据当前路由 (route)，从完整的菜单列表 (menuRoutes) 中，找到最匹配的那个菜单项路径。修改SidebarMenu.vue：

<script setup lang="ts"> import { computed } from 'vue' import { useRoute } from 'vue-router' import MenuItem from './MenuItem.vue' import type { MenuItem as MenuItemType } from './types' // 假设有类型定义 defineProps<{ isCollapse: boolean }>() const route = useRoute() const menuRoutes: MenuItemType[] = [ ... ] // 你的菜单数据 /** * 递归查找与当前路由路径最匹配的菜单项 * @param path 当前路由路径 * @param menuList 菜单列表 * @returns 匹配到的菜单项路径，未找到则返回当前路由路径 */ const findActiveMenu = (path: string, menuList: MenuItemType[]): string => { for (const menu of menuList) { // 精确匹配：当前路径完全等于菜单路径 if (menu.path === path) { return menu.path } // 前缀匹配：当前路径以菜单路径开头（考虑嵌套路由） // 例如 path=/system/user, menu.path=/system // 需要确保不是根路径，且匹配后下一个字符是 '/'，避免 /sys 匹配到 /system if (path.startsWith(menu.path + '/') && menu.path !== '/') { return menu.path } // 递归查找子菜单 if (menu.children && menu.children.length > 0) { const activePath = findActiveMenu(path, menu.children) if (activePath) { // 如果子菜单中找到了，可以返回子菜单的路径，或者根据需求返回父菜单路径 // 通常，我们希望高亮父级菜单（即当前这个menu） return menu.path } } } return path // 兜底，返回当前路径 } // 计算当前激活的菜单项 const activeMenu = computed(() => { return findActiveMenu(route.path, menuRoutes) }) </script>

这个findActiveMenu函数实现了：

• 精确匹配：第一优先级。
• 前缀匹配：用于处理嵌套路由，高亮父级菜单。
• 递归查找：深入子菜单进行匹配。

经验技巧：在实际项目中，菜单数据往往来自后端接口，其结构可能更复杂。你可能需要处理meta中定义的activeMenu字段（Vue Router 支持），或者根据路由的name进行匹配。上述函数是一个基础但有效的解决方案，你可以根据项目实际情况调整匹配逻辑。例如，有些场景下，你希望高亮的是叶子节点菜单，而不是父节点，那么递归查找时返回activePath而不是menu.path即可。

6.3 处理路由变化时菜单的展开状态

另一个相关的问题是：当通过浏览器地址栏或链接跳转到一个深层路由时，对应的父级子菜单应该自动展开。Element-Plus 的<el-menu>组件有default-openeds属性可以设置默认展开的菜单，但它是静态的。我们需要动态设置。

我们可以利用 Vue Router 的导航守卫或watch来监听路由变化，然后计算出需要展开的菜单索引数组。

<!-- 在 SidebarMenu.vue 中补充 --> <template> <el-menu :default-active="activeMenu" :default-openeds="openedMenus" :collapse="isCollapse" ...其他属性 > ... </el-menu> </template> <script setup lang="ts"> import { ref, watch, computed } from 'vue' import { useRoute } from 'vue-router' const route = useRoute() const menuRoutes = [ ... ] const isCollapse = defineProps... // 存储当前需要展开的菜单项 index (path) 数组 const openedMenus = ref<string[]>([]) /** * 根据当前活动路径，找出所有需要展开的父级菜单路径 */ const updateOpenedMenus = (activePath: string, menuList: MenuItemType[]): string[] => { const opened: string[] = [] const findPath = (path: string, list: MenuItemType[], parentPaths: string[] = []): boolean => { for (const menu of list) { const currentPaths = [...parentPaths, menu.path] if (menu.path === path || path.startsWith(menu.path + '/')) { // 找到匹配项，将其所有父路径加入展开列表（排除自身） opened.push(...parentPaths) return true } if (menu.children) { if (findPath(path, menu.children, currentPaths)) { // 如果在子菜单中找到，当前菜单也需要展开 if (!opened.includes(menu.path)) { opened.push(menu.path) } return true } } } return false } findPath(activePath, menuRoutes) // 去重并返回 return [...new Set(opened)] } // 监听 activeMenu 变化，更新展开的菜单 watch( () => activeMenu.value, (newPath) => { openedMenus.value = updateOpenedMenus(newPath, menuRoutes) }, { immediate: true } // 立即执行一次以初始化 ) </script>

这样，无论用户通过何种方式进入页面（刷新、直接输入URL、点击面包屑等），对应的菜单层级都会正确展开，高亮也准确无误，提供了完整的导航体验。

7. 性能优化与细节打磨

功能实现后，我们还需要关注性能和用户体验细节。

7.1 避免不必要的重渲染

我们的SidebarMenu和MenuItem组件在isCollapse变化或路由变化时可能会重新渲染。对于大型菜单，这可能有性能开销。

1. 使用v-once或Object.freeze：如果菜单数据是静态的，在定义时可以使用Object.freeze冻结，或对无需响应的部分使用v-once指令。但我们的菜单数据可能来自接口，需谨慎。
2. 精细化传递 Props：确保只将必要的 props 传递给子组件。例如，MenuItem组件只需要当前的item数据，不需要知道全局的isCollapse状态。
3. 使用computed缓存：像activeMenu、asideWidth这样的派生状态，一定要用computed计算属性，Vue 会帮我们做缓存。

7.2 折叠状态下的用户体验提升

• 标题 Tooltip：当菜单折叠时，鼠标悬停在图标上，应该显示该菜单项的完整标题。Element-Plus 的<el-menu>在collapse状态下会自动为el-sub-menu添加 Tooltip，但对于el-menu-item，我们需要自己处理。一种简单的方式是给每个el-menu-item包裹一个el-tooltip，但这样代码侵入性强。更优雅的方式是利用el-menu的popper-effect和collapse状态下的内置行为，通常已经够用。如果不够，可以监听isCollapse，动态为每个菜单项的根元素添加title属性。
• 折叠动画节奏：我们为侧边栏宽度和菜单文字都添加了 CSS 过渡。确保两者的持续时间和缓动函数 (easing-function) 一致或协调，例如都使用ease-in-out和0.3s，这样动画看起来才是一体的，不会脱节。

7.3 与 Pinia (状态管理) 的集成

在大型项目中，菜单的折叠状态可能需要在多个不相关的组件中访问（例如，一个在页面深处的按钮也想控制菜单折叠）。这时，将isCollapse放在全局状态管理库（如 Pinia）中会更合适。

// stores/app.ts import { defineStore } from 'pinia' import { useLocalStorage } from '@/composables/useLocalStorage' export const useAppStore = defineStore('app', () => { const isCollapse = useLocalStorage<boolean>('app-sidebar-collapse', false) const toggleCollapse = () => { isCollapse.value = !isCollapse.value } return { isCollapse, toggleCollapse } })

然后在Layout.vue和任何需要的地方引入并使用这个 store：

<!-- Layout.vue --> <script setup lang="ts"> import { useAppStore } from '@/stores/app' import { storeToRefs } from 'pinia' const appStore = useAppStore() // 使用 storeToRefs 保持响应式 const { isCollapse } = storeToRefs(appStore) const { toggleCollapse } = appStore // ... 其余逻辑 </script>

这样，状态管理更加清晰，也满足了跨组件状态共享的需求。

8. 常见问题排查与解决方案

在实际开发中，你可能会遇到以下问题：

问题一：菜单折叠后，子菜单的弹出位置错乱，或者被遮挡。

• 原因：Element-Plus 的<el-menu>在collapse状态下，子菜单会以popper（浮层）形式弹出。这个浮层的z-index可能不够高，或者其父容器设置了overflow: hidden。
• 解决方案：
  1. 检查.layout-aside或.sidebar-menu的父容器是否有overflow: hidden。如果有，尝试移除或改为overflow: visible。在我们的代码中，.layout-aside设置了overflow: hidden是为了防止收缩时内容溢出，但这可能会裁剪浮层。一个折中方案是只在非折叠状态下隐藏溢出：overflow: hidden;配合overflow: visible !important;在折叠状态下（通过:deep(.el-menu--collapse)选择器）可能不理想。更稳妥的做法是，确保浮层弹出的根节点 (body) 不受影响。Element-Plus 的popper默认会附加到body末尾，通常不受父容器影响。如果仍有问题，可以调整<el-menu>的popper-append-to-body属性（默认为true，应保持），并检查全局CSS是否有影响body下元素的样式。

问题二：路由跳转后，页面内容区域滚动条没有复位到顶部。

• 原因：这是单页应用 (SPA) 的常见问题。路由切换时，Vue Router 复用了组件，页面容器（我们的el-main）的滚动位置保持不变。
• 解决方案：在Layout.vue中，监听路由变化，并滚动主容器到顶部。

  <!-- 在 Layout.vue 的 script 部分 --> import { useRouter } from 'vue-router' const router = useRouter() const layoutMainRef = ref<HTMLElement>() // 给 el-main 加上 ref="layoutMainRef" router.afterEach(() => { // 等待下一个渲染周期，确保 DOM 已更新 nextTick(() => { const mainEl = layoutMainRef.value?.$el || layoutMainRef.value if (mainEl) { mainEl.scrollTop = 0 } }) })

问题三：在移动端，点击菜单项跳转后，抽屉不会自动关闭。

• 原因：我们的mobileSidebarOpen状态只响应了遮罩层和按钮的点击事件，没有监听路由变化。
• 解决方案：在Layout.vue中，添加一个对路由的监听，当路由变化时，在移动端自动关闭抽屉。

  <script setup lang="ts"> import { useRouter } from 'vue-router' const router = useRouter() // ... 其他代码 // 监听路由变化，在移动端关闭抽屉 router.afterEach(() => { if (isMobile.value) { closeMobileSidebar() } }) </script>

问题四：菜单图标在折叠状态下不居中或样式错乱。

• 原因：Element-Plus 的<el-menu>在折叠状态下，会为菜单项添加特定的样式类，如el-menu--collapse。我们自定义的样式可能与之冲突。
• 解决方案：使用深度选择器:deep()来覆盖或调整 Element-Plus 的默认样式，并且要确保我们的样式优先级足够。例如，确保我们之前写的折叠状态下隐藏文字并添加过渡的 CSS 正确生效。如果图标不居中，可以检查.el-menu--collapse .el-menu-item和.el-menu--collapse .el-sub-menu__title的padding和text-align属性。

通过以上八个部分的详细拆解，我们从零到一构建了一个健壮、美观且用户体验良好的 Vue3 + Element-Plus 左侧菜单折叠展开功能。它不仅实现了基础交互，更深入解决了状态持久化、响应式适配、路由高亮、性能细节等实际开发中必然会遇到的难题。每个步骤都附带了原理说明和踩坑经验，你可以直接将这些代码和思路应用到你的项目中，根据实际需求进行调整，相信能帮你打造出一个令人满意的导航菜单。