推荐使用Bootstrap 5.2+的offcanvas组件实现侧边栏滑动弹出，因其原生支持触控、ESC关闭、遮罩点击关闭、键盘导航，无障碍合规且响应式可靠；DOM须为body直接子元素，data-bs-toggle与data-bs-target须严格匹配，方向类用offcanvas-start/offcanvas-end，关闭按钮需在内部并带data-bs-dismiss="offcanvas"，滚动控制须作用于offcanvas-body。
直接用 Bootstrap 5.2+ 的 offcanvas 组件，别手写 transform 动画——它原生支持、无障碍合规、响应式可靠，且 JS 初始化后开箱即用。
为什么 offcanvas 是唯一推荐方案
Bootstrap 官方明确将侧边栏滑动弹出定义为 offcanvas 场景，不是 collapse、dropdown 或自定义 transform 的替代品。v5.2 起 offcanvas 已稳定支持移动端触控、ESC 关闭、遮罩点击关闭、键盘导航等核心交互，而手动实现的 transform 方案在 iOS Safari 下易卡顿、遮罩层不联动、无法监听 ESC、且破坏语义结构。
- offcanvas 默认启用 backdrop 和 keyboard 支持，无需额外配置
- 方向类（如
offcanvas-start）自动适配 RTL，offcanvas-end在阿拉伯语页面会从左滑入 - 滚动行为由
offcanvas-body独立控制，不会带动遮罩层一起滚动 - DOM 必须是
<body>直接子元素，否则被父容器overflow: hidden截断或定位偏移
data-bs-toggle 和 data-bs-target 配对必须严格一致
点击无反应的首要原因永远是这两个属性没对上。不是“差不多就行”，而是大小写、连字符、ID 值必须逐字匹配。
- 触发按钮必须同时含
data-bs-toggle="offcanvas"和data-bs-target="#sidebar-menu"（或href="#sidebar-menu"） - 目标
<div>的id必须是sidebar-menu，不能是sidebarMenu或sidebar_menu - 不要把
offcanvas写在<header>或<main>里——它得是<body>的第一层子节点 - v4 升级 v5 时常见错误：
data-toggle漏掉bs-前缀，浏览器完全忽略该属性
方向类和关闭按钮位置不能错
方向不是靠 CSS 变量或 JS 参数控制，全靠 class 名；关闭逻辑则强依赖 DOM 位置和属性值。
- 左侧滑入必须用
offcanvas-start（不是offcanvas-left），右侧用offcanvas-end - 关闭按钮必须是
<button type="button" class="btn-close" data-bs-dismiss="offcanvas"></button>，且必须放在offcanvas内部（不能在外层 div 里） - 写成
data-dismiss="offcanvas"（少bs-）或放在offcanvas-header外，点击无效 - 手动 JS 关闭要用
bootstrap.Offcanvas.getInstance(el).hide()，别直接删show类，否则遮罩残留
内容滚动必须作用于 offcanvas-body
抽屉内容撑满屏幕却无法滚动？问题几乎总是出在滚动样式没加对容器上。
- 给
<div class="offcanvas-body">加max-height: calc(100vh - 56px)（减去 header 高度）和overflow-y: auto - 不要给最外层
offcanvas设height或overflow，会破坏动画定位 -
offcanvas-body里放菜单项、表单、链接均可，但避免嵌套另一个offcanvas - 如果用了自定义顶部栏，把它放进
offcanvas-header，别混进offcanvas-body
真正容易被忽略的是：offcanvas 的 DOM 位置和方向类必须同步生效——哪怕 HTML 结构正确，若 JS 在 DOM 尚未就绪时就初始化实例，getElementById 返回 null，整个组件静默失效。确保 Bootstrap JS 在 <body> 底部加载，或用 DOMContentLoaded 包裹手动初始化逻辑。
