★ FEATURED ARTICLE 前端UI组件【免费下载链接】uiThe Intuitive Vue UI Library powered by Reka UI Tailwind CSS.项目地址https://gitcode.com/gh_mirrors/ui4/ui点击查看免费下载DashboardSidebar 是 Nuxt UI 中专门为仪表盘Dashboard布局设计的侧边栏组件支持拖拽调整宽度、靠近边缘自动折叠、状态持久化并与DashboardGroup、DashboardPanel、DashboardNavbar等组件深度集成。读完本文你将掌握其完整用法如何在布局中接入、如何配置可调整/可折叠行为、如何用mode与插槽定制菜单与内容、如何通过v-model控制开合状态以及其背后的持久化与底层实现原理。组件定位DashboardSidebar 与 Sidebar 的区别在开始使用之前需要先明确DashboardSidebar与普通 Sidebar 的适用场景。二者同名但定位完全不同DashboardSidebar专为仪表盘布局设计核心能力是拖拽调整宽度drag-to-resize、状态持久化state persistence以及与DashboardGroup等仪表盘组件体系的集成适合数据面板、管理后台这类需要可自由调节空间的场景Sidebar是独立的轻量侧边栏适合聊天面板、设置页、普通导航等不需要拖拽调整的简单场景。从源码看DashboardSidebar的接口直接继承自useResizablecomposable 的尺寸相关属性id、side、minSize、maxSize、defaultSize、resizable、collapsible、collapsedSize见 src/runtime/components/DashboardSidebar.vue这正是它与普通侧边栏的本质差异所在。基本用法嵌入 DashboardGroup 布局DashboardSidebar必须放置在DashboardGroup的默认插槽中由其提供共享的上下文context。一个典型的仪表盘布局文件如下template UDashboardGroup UDashboardSidebar / slot / /UDashboardGroup /template⚠️注意单一根元素问题当使用resizable属性时该组件没有单一根元素其模板会额外渲染拖拽手柄和菜单浮层。如果项目使用了页面过渡动画page transitions或需要单一根节点的布局场景请用容器包裹例如div classflex flex-1。组件结构上支持三个区域插槽header、footer用于自定义侧边栏的顶部与底部区域default侧边栏主体内容body/content用于自定义侧边栏菜单menu部分。Props 全解析与默认值DashboardSidebar的完整属性定义位于 src/runtime/components/DashboardSidebar.vue下面是每个属性的含义与源码中的默认值属性类型默认值说明sideleft \| rightleft侧边栏渲染在哪一侧modemodal \| slideover \| drawerslideover侧边栏菜单移动端浮层的呈现模式menu取决于mode的组件 Props—传递给菜单组件的属性随mode自适应toggleboolean \| ButtonPropstrue是否显示移动端打开按钮可传Button组件属性自定义toggleSideleft \| rightleft切换按钮的位置autoClosebooleantrue路由变化时是否自动关闭侧边栏minSizenumber10最小尺寸maxSizenumber20最大尺寸defaultSizenumber15默认尺寸resizablebooleanfalse是否允许拖拽调整collapsiblebooleanfalse是否允许拖到边缘时折叠collapsedSizenumber0折叠后的尺寸idstringuseId()唯一标识用于持久化键名与无障碍关联open/collapsedbooleanfalse可通过v-model双向绑定控制的状态其中minSize、maxSize、defaultSize默认值10 / 20 / 15是百分比含义详见下文「Size」一节且resizable与collapsible默认都是关闭的需要显式开启。持久化存储由 DashboardGroup 决定侧边栏的状态尺寸、折叠与否等会保存到存储中而存储方式由DashboardGroup的storage与storage-key属性决定DashboardGroup 属性默认值说明storagecookie存储介质可选cookie或locallocalStoragestorageKeydashboard存储键名前缀persistenttrue是否持久化尺寸unit%尺寸单位可选%、rem、px对应源码见 src/runtime/components/DashboardGroup.vue 与useResizable的存储逻辑 src/runtime/composables/useResizable.ts当persistent开启且组件可调整或可折叠时cookie模式使用useCookie、local模式使用useStorage关闭持久化时则退化为普通响应式ref。Toggle 按钮与自适应性toggle属性控制移动端用于打开侧边栏的按钮。传true时使用默认的DashboardSidebarToggle组件也可以传入一个对象此时对象中的任意属性都会透传给底层的 Button 组件例如UDashboardSidebar :toggle{ color: primary, variant: solid } /toggle-side属性则控制该按钮渲染在左侧还是右侧默认left。从实现看按钮的图标会根据当前开合状态切换打开时为close图标关闭时为menu图标并带有相应的aria-label见 src/runtime/components/DashboardSidebarToggle.vue。Resizable开启拖拽调整给侧边栏加上resizable属性即可让用户通过拖拽边缘手柄来调整宽度UDashboardSidebar resizable :min-size22 :default-size35 :max-size40 /开启后组件会在侧边栏的一侧渲染一个拖拽手柄DashboardResizeHandle并暴露resize-handle插槽供自定义。底层由useResizable实现完整的拖拽逻辑src/runtime/composables/useResizable.ts鼠标与触摸事件均被支持onMouseDown/onTouchStart通过监听全局mousemove/touchmove计算位移拖拽过程中实时将新宽度写入size并通过Math.min(maxSize, Math.max(minSize, newValue))钳制在minSize与maxSize之间双击拖拽手柄会恢复为defaultSizeonDoubleClick见 useResizable.ts在RTL从右到左语言环境下位移增量的方向会自动反转计算useResizable.ts。Collapsible拖到边缘自动折叠配合resizable使用collapsible属性可以让用户把侧边栏拖到屏幕边缘附近时自动折叠UDashboardSidebar resizable collapsible :min-size22 :default-size35 :max-size40 /折叠判定的阈值在useResizable中实现当拖拽计算出的新尺寸小于collapsedSize 4时自动折叠useResizable.ts折叠后再拖拽或调大尺寸则会自动展开并恢复折叠前的宽度previousSize会被暂存见 useResizable.ts。⚠️重要约束DashboardSidebarCollapse 组件只有在侧边栏设置了collapsible时才有效否则点击无效。在插槽中感知折叠状态折叠状态会通过插槽 props 暴露给header、default、footer插槽{ collapsed, collapse }方便你在折叠后切换内容。例如可以在侧边栏折叠时只显示图标、隐藏文字。Size尺寸控制四件套min-size、max-size、default-size与collapsed-size四个属性共同决定侧边栏的尺寸行为UDashboardSidebar resizable collapsible :min-size22 :default-size35 :max-size40 :collapsed-size0 /两点需要特别说明默认以百分比计算文档示例中的35表示占据父容器宽度的 35%。如果需要改用rem或px通过DashboardGroup的unit属性切换见上文表格。useResizable在rem模式下会读取根元素fontSize进行像素换算useResizable.tscollapsed-size默认是0但主题为根节点设置了min-w-16最小宽度 4rem保证即使折叠到 0 也仍然能看到侧边栏的残余轮廓避免完全消失对应主题见 src/theme/dashboard-sidebar.ts。Side切换侧边栏方向side属性默认为left改为right即可把侧边栏渲染到右侧UDashboardSidebar sideright resizable collapsible /从主题源码可以观察到方向差异的处理左侧侧边栏根节点带border-e border-default右侧边框线右侧侧边栏则没有src/theme/dashboard-sidebar.ts拖拽手柄也会根据side被渲染到对应的一侧。Mode侧边栏菜单的三种浮层模式在移动端小于lg断点侧边栏会隐藏为浮层菜单mode属性决定浮层的呈现方式默认slideovermodal模态对话框对应Modal组件源码中会自动补上fullscreen: true, transition: falseslideover从左侧滑出对应Slideover组件自动补side: leftdrawer抽屉式对应Drawer组件。选择逻辑见 src/runtime/components/DashboardSidebar.vueMenu是一个根据mode动态映射到USlideover/UModal/UDrawer的计算属性。用menu属性定制浮层menu属性用于向菜单组件透传属性它会随mode的类型自适应modal时是ModalProps、slideover时是SlideoverProps、drawer时是DrawerProps并通过defu与mode自动注入的默认值合并DashboardSidebar.vue。例如UDashboardSidebar modeslideover :menu{ side: right } /菜单区域的内容可以通过插槽定制body插槽填充头部下方的菜单主体content插槽则填充整个菜单。测试用例覆盖了三种mode的渲染见 test/components/DashboardSidebar.spec.ts。提示文档中的移动端示例之所以同时包含DashboardGroup、DashboardPanel与DashboardNavbar是因为演示移动端效果需要完整的仪表盘容器。Toggle 与 Toggle Side移动端开合按钮toggle与toggle-side配合用于移动端打开侧边栏浮层UDashboardSidebar toggle toggle-sideright /toggle接受boolean或 Button 属性对象{ color: neutral, variant: ghost }是默认观感toggle-side控制按钮在菜单头部中的位置主题中右侧按钮会自动应用ms-auto推向最右src/theme/dashboard-sidebar.ts。Examples用 v-model 掌控开合与折叠状态控制打开状态通过open属性或v-model:open指令即可完全控制侧边栏的打开/关闭UDashboardSidebar v-model:openopen /文档示例还演示了结合 defineShortcuts 注册键盘快捷键按O键即可切换侧边栏的开合状态。控制折叠状态类似地collapsed属性与v-model:collapsed指令用于控制折叠状态UDashboardSidebar v-model:collapsedcollapsed resizable collapsible /示例中通过defineShortcuts注册了按C键切换折叠。从源码看外部传入的collapsedref 会与内部useResizable的折叠状态双向同步初始化时从存储恢复、运行时通过watch双向同步useResizable.ts。深入底层状态持久化、Context 与运行时钩子持久化如何工作DashboardSidebar的持久化键由storageKey来自DashboardGroup默认dashboard加-sidebar-加id或useId()生成的唯一 ID拼接而成。每次尺寸或折叠状态变化都会写入存储下次加载时自动恢复DashboardSidebar.vue。useResizable还做了防御性处理如果读取到损坏的null存储值会在写入时自动重建为默认值useResizable.ts。Context 如何共享DashboardGroup通过provideDashboardContext注入包含storage、storageKey、unit、sidebarOpen、sidebarCollapsed、toggleSidebar、collapseSidebar等字段的上下文见 src/runtime/utils/dashboard.ts 与 src/runtime/components/DashboardGroup.vue。DashboardSidebar、DashboardSidebarToggle、DashboardSidebarCollapse都通过useDashboard()消费这份上下文从而实现跨组件联动。Runtime HooksDashboardGroup将toggleSidebar与collapseSidebar封装为 Nuxt 运行时钩子调用dashboard:sidebar:toggle切换打开状态dashboard:sidebar:collapse设置折叠状态。DashboardSidebar内部通过useRuntimeHook监听这两个钩子来同步自身状态DashboardSidebar.vue这为第三方扩展或命令式调用提供了统一的入口。autoClose路由变化自动关闭autoClose默认为true组件会监听route.fullPath路由变化时自动关闭侧边栏DashboardSidebar.vue。在带路由跳转的导航场景下无需手动处理关闭逻辑若侧边栏在非路由场景使用例如纯状态面板可将其关闭。Slots 一览组件共暴露 6 个插槽完整签名见 DashboardSidebar.vue插槽作用插槽 Propsheader侧边栏顶部区域collapsed,collapse(value)default侧边栏主体collapsed,collapse(value)footer侧边栏底部区域collapsed,collapse(value)toggle自定义移动端切换按钮open,toggle(),uicontent自定义整个浮层菜单close?()resize-handle自定义拖拽手柄onMouseDown,onTouchStart,onDoubleClick,ui测试中已对全部 6 个插槽逐一做了快照渲染验证test/components/DashboardSidebar.spec.ts。主题定制组件的视觉样式统一由主题文件 src/theme/dashboard-sidebar.ts 定义包含root、header、body、footer、toggle、handle、content、overlay等插槽类并带有menu浮层菜单下的内边距与side两个变体。关键设计rootrelative hidden lg:flex flex-col min-h-svh min-w-16 w-(--width) shrink-0—— 桌面端lg以上显示为 flex 纵向布局宽度由 CSS 变量--width驱动该变量由组件内联写入--width: ${size}${unit}content/overlay默认lg:hidden即浮层菜单只在移动端出现。与所有 Nuxt UI 组件一致你可以通过ui属性或appConfig.ui.dashboardSidebar覆盖任意插槽样式。质量保障测试与无障碍组件测试位于 test/components/DashboardSidebar.spec.ts覆盖了全部核心 Propsid、side、尺寸四件套、resizable、collapsible、三种mode、toggle开关与对象形式、toggleSide、ui定制等的快照渲染菜单对话框的无障碍标签打开时对话框以本地化文案如 Open sidebar作为aria-labelledby标题axe 无障碍自动检测resizable collapsible组合下零违规DashboardSidebar.spec.ts。这保证了组件在复杂交互拖拽、折叠、浮层下仍符合可访问性要求。总结DashboardSidebar是构建可交互、可持久化仪表盘布局的核心组件通过resizable/collapsible提供桌面端的拖拽与自动折叠体验通过mode/menu/toggle提供移动端的浮层导航通过DashboardGroup统一管理存储与单位并通过v-model:open/v-model:collapsed与运行时钩子保持状态可控。结合useResizable的底层实现RTL 适配、双击恢复、折叠阈值、存储防御与完整的测试保障它可以直接成为你下一个管理后台布局的可靠基础设施。赞分享前端UI组件【免费下载链接】uiThe Intuitive Vue UI Library powered by Reka UI Tailwind CSS.项目地址https://gitcode.com/gh_mirrors/ui4/ui点击查看免费下载相关推荐Nuxt UI 的 DashboardSidebarCollapse 组件桌面端侧边栏折叠按钮的完整实战指南Nuxt UI 的 DashboardSidebarCollapse 组件桌面端侧边栏折叠按钮的完整实战指南 DashboardSidebarCollapse前端UI组件AReaL-tau2-airline-sft-30B多模态能力探索视觉与文本融合的航空应用AReaL tau2 airline sft 30B多模态能力探索视觉与文本融合的航空应用 AReaL tau2 airline sft 30B是一款专为航空前端UI组件CSS Layout侧边栏可折叠侧边栏实现CSS Layout侧边栏可折叠侧边栏实现 你是否还在为网页布局中的侧边栏实现而烦恼是否想要一个既美观又实用的可折叠侧边栏解决方案本文将为你详细介绍如何使教程前端上一篇Yaak API客户端插件依赖冲突如何快速解决npm包版本兼容性问题下一篇Odysseus 对接 Claude Code 实战作用域 API、能力开关与 Cookbook 模型服务调试闭环创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
函数用法讲解)
函数用法与实例讲解)
