必须用 .list-group 包裹所有菜单项，因其语义清晰、支持交互态且适配垂直布局；误用 .nav 会导致响应和可访问性问题。
必须用 .list-group 包裹所有菜单项，不能只靠 .nav 或 .dropdown
Bootstrap 5 的 .list-group 是侧边菜单最轻量、语义最清晰的选择——它天然支持点击态（.active）、禁用态（.disabled）、分隔线（.list-group-divider），且不依赖 JS 就能响应 hover/focus。很多人误用 .nav 套在 sidebar 里，结果发现移动端点不中、键盘 tab 跳转错乱，就是因为 .nav 默认是 inline-flex，而 .list-group 是 block 布局，更适配垂直菜单流。
实操建议：
- 每个菜单项必须是
<a></a>或<button></button>，并加.list-group-item类；直接写<div class="list-group-item"> 会丢失可访问性（无 role、无 tabindex）<li>不要把整个 <code>.list-group塞进.offcanvas-body以外的容器里——比如嵌套在.col或.card中，否则可能被overflow: hidden截断滚动 - 若需图标+文字，用
<i class="fas fa-home me-2"></i>首页，别用<span></span>包图标，避免额外行高干扰对齐 - 鼠标悬停没变化，点击后也无视觉反馈
- 用屏幕阅读器时读不出“可点击”状态
- 在触摸设备上点一下没反应，要连点两下才触发
.list-group-item-action 是点击反馈的关键，不是可选项
没有 .list-group-item-action，菜单项只有基础样式，不会变色、不会加手型光标、键盘按 Enter 也不会触发 click。这个类本质是给 <a></a> 和 <button></button> 注入交互语义，不是装饰用的。
常见错误现象：
正确写法示例：
<a href="#dashboard" class="list-group-item list-group-item-action"> <i class="fas fa-tachometer-alt me-2"></i>仪表盘 </a>
展开子菜单得靠 .collapse + 手动控制高度，.list-group 不内置折叠逻辑
.list-group 本身不处理层级展开，要实现“点击父项展开子项”，必须配合 Bootstrap 的 .collapse 插件。不能只靠 CSS display: none/block 切换，否则动画失效、无障碍属性缺失、键盘焦点管理失控。
实操要点：
- 父项用
<button></button>触发，加data-bs-toggle="collapse"和data-bs-target="#submenu1" - 子项用
<div class="collapse"><div class="list-group">...</div></div>包裹，id 必须与data-bs-target严格一致 - 必须为
.collapse设置max-height（如max-height: 300px），否则展开时高度从 0 突变，无过渡动画 - 别把多个
.collapse套在同一级.list-group里——它们会互相影响高度计算，导致折叠错位
移动端滚动卡顿？问题大概率出在 .list-group 外层容器没设 max-height 和 overflow-y: auto
长菜单在手机上拖不动、滑到一半突然跳回顶部，往往不是 JS 问题，而是 CSS 流式溢出没控住。Bootstrap 的 .list-group 默认不限高，内容一多就撑爆视口，遮罩层和关闭按钮被顶出可视区。
解决路径很明确：
- 给
.list-group的直接父容器（比如.offcanvas-body或自定义 sidebar 容器）加max-height: calc(100vh - 56px)（减去 header 高度） - 同时加
overflow-y: auto，别用scroll—— 后者在 iOS Safari 上可能触发非预期弹性滚动 - 如果用了自定义 header（比如带
.offcanvas-header的抽屉），确保它的高度参与计算，别硬写56px，改用 CSS 变量或100dvh提升兼容性 - 检查是否误给
.list-group自身加了height或min-height—— 这会破坏 collapse 动画的 height 计算逻辑
真正容易被忽略的是：当菜单项超过 10 条、又嵌套了 2 层 collapse 时，max-height 的值必须大于所有可能展开状态的总高度，否则最后一层展开会被截断。这不是 Bug，是 CSS 过渡动画的固有限制——它只能基于当前元素的 computed height 做插值，没法动态重算。
