Bootstrap 5.2+ 原生 offcanvas 组件通过 data-bs-toggle="offcanvas" 触发，需配合 data-bs-target、offcanvas 类容器及 bootstrap.bundle.min.js；常见问题包括 ID 不匹配、JS 未引入、事件监听时机错误或移动端手势冲突。
用 data-bs-toggle="offcanvas" 启动原生 offcanvas 组件
bootstrap 5.2+ 内置了 offcanvas，不用自己写 js 或 css 动画。核心是给按钮加 data-bs-toggle="offcanvas"，再指向一个带 offcanvas 类的容器。它比手写侧滑菜单更稳，兼容性好，响应式也默认支持。
常见错误：漏掉 data-bs-target 或 ID 不匹配，点不动；或者没引入 bootstrap.bundle.min.js（因为依赖 Popper 和基础 JS 模块）。
- 按钮必须有
data-bs-toggle="offcanvas"和data-bs-target="#myOffcanvas" - 侧边菜单容器需有
class="offcanvas offcanvas-start"（offcanvas-end表示右侧弹出） - 容器必须有对应
id="myOffcanvas"，且不能重复 - 确保页面已加载
bootstrap.bundle.min.js，不是仅bootstrap.min.css
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#sidebar">打开菜单</button>
<div class="offcanvas offcanvas-start" tabindex="-1" id="sidebar">
<div class="offcanvas-header">
<h5 class="offcanvas-title">菜单</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas"></button>
</div>
<div class="offcanvas-body">
<a href="#" class="d-block py-2">首页</a>
<a href="#" class="d-block py-2">设置</a>
</div>
</div>
关闭时触发回调：监听 hide.bs.offcanvas 事件
有些场景需要在菜单收起后重置表单、暂停轮播或释放资源。Bootstrap 提供了标准事件，比直接绑 click 更可靠——比如用户点遮罩层、按 ESC、或调用 offcanvas.hide() 都会触发。
容易踩的坑：用 hidden.bs.offcanvas（已完成）代替 hide.bs.offcanvas（即将开始），导致逻辑执行晚了一拍；或者没在 DOM 就绪后绑定事件。
- 监听
hide.bs.offcanvas可在动画开始前干预，适合清理操作 - 监听
hidden.bs.offcanvas表示已完全隐藏，适合后续状态同步 - 事件必须在
offcanvas元素上监听，不是按钮上 - 推荐用
document.addEventListener('DOMContentLoaded', ...)包裹
document.addEventListener('DOMContentLoaded', () => {
const myOffcanvas = document.getElementById('sidebar');
myOffcanvas.addEventListener('hide.bs.offcanvas', event => {
console.log('菜单正要收起');
// 例如：清空搜索框
document.querySelector('#search-input').value = '';
});
});
移动端适配：避免 offcanvas 被系统手势拦截
在 iOS Safari 或部分安卓浏览器里，侧滑菜单可能和系统返回/前进手势冲突，导致拖拽卡顿或直接失效。根本原因是 offcanvas 的 transform 动画被浏览器优化跳过，或 touch 事件未正确捕获。
这不是 Bootstrap bug，而是 Webview 层级限制。绕过方式很具体，不是加个 !important 就能解决。
- 给
.offcanvas加touch-action: pan-y;（禁止横向拖拽干扰） - 确保父容器没有
overflow: hidden或transform: translateZ(0)类似 hack - 如果用了自定义滚动区域（如
.offcanvas-body { overflow-y: auto; }），需额外加-webkit-overflow-scrolling: touch; - 避免在
offcanvas上同时使用position: fixed和大量z-index层叠
不依赖 Bootstrap JS 时的轻量替代方案
如果项目只用 Bootstrap CSS、不想引入 JS，或者需要更细粒度控制动画节奏，可以用纯 CSS + 少量 JS 切换类实现。关键在于用 transform: translateX() 替代 display 切换，保证硬件加速。
注意：这种写法失去 backdrop 遮罩、ESC 关闭、焦点管理等特性，得自己补。别为了“轻量”把交互做残。
- 菜单容器初始设
transform: translateX(-100%);，并加transition: transform 0.3s ease; - 按钮点击时给 body 加 class（如
menu-open），然后用.menu-open .sidebar { transform: translateX(0); } - 遮罩层用伪元素或单独
div，监听点击自身或 ESC 键手动移除 class - 务必用
inert属性或aria-hidden="true"控制可访问性
真实项目里，只要不是超低资源环境，优先用原生 offcanvas。自己写的容易在键盘导航、屏幕阅读器、焦点环恢复上出问题，这些细节比动画多花三倍时间。
