Bootstrap 5 的 offcanvas 必须作为 body 直接子元素、设唯一 id 并匹配 data-bs-target，配合 data-bs-placement 控制方向；遮罩关闭失效多因 DOM 未就绪或 id 错误；侧边栏滚动需在 offcanvas-body 设 max-height 和 overflow-y: auto。
用 Bootstrap 5 的 offcanvas 实现侧边栏抽屉
bootstrap 5 原生支持抽屉（offcanvas），不用自己写 css 或 js 就能实现侧边栏滑出效果。关键不是“怎么加动画”，而是“怎么让 offcanvas 正确挂载到 body、不被父容器裁剪、且能响应点击/esc 关闭”。
常见错误是直接把 offcanvas 写在某个 div 里，结果被 overflow: hidden 截断，或者点击遮罩层没反应——因为 Bootstrap 要求它必须是 body 的直接子元素。
- 把
<div class="offcanvas">放在<body>最外层，**不能嵌套在container、row或任何带overflow的容器里** - 必须配
id，且触发按钮的data-bs-target要严格匹配（比如#sidebar-offcanvas） - 加
data-bs-placement="start"控制从左侧滑出；用"end"是右侧；"top"/"bottom"是上下 - 如果页面已有
position: fixed的 header 或 footer，要确保offcanvas的z-index高于它们（默认是 1200，一般够用）
为什么 offcanvas 点击遮罩不关闭？
遮罩层（backdrop）默认是启用的，但关闭行为依赖两个条件：一是 data-bs-backdrop="true"（默认值，可省略），二是 data-bs-keyboard="true"（默认也开启）。真正卡住的是 JS 初始化或事件绑定失败。
- 检查控制台有没有
TypeError: Cannot read properties of null (reading 'addEventListener')—— 这说明document.getElementById()没拿到目标元素，id拼错了或 DOM 还没加载完就执行了 JS - 如果你用
defer加载 Bootstrap JS，确保offcanvas的 HTML 在<body>里已存在，而不是后续 JS 动态插入的 -
data-bs-backdrop="false"会禁用遮罩，此时点击当然无效；设成"static"则点击遮罩不关闭，但 ESC 仍可用
如何让侧边栏内容滚动而遮罩不滚动？
默认情况下，整个 offcanvas 区域会随内容撑高，遮罩层也会跟着拉长。但用户想要的是“侧边栏内部滚动，背景不动”。这靠两步：固定高度 + 内部溢出控制。
- 给
offcanvas-body加max-height: calc(100vh - 56px)（减去 header 高度），再加overflow-y: auto - 不要给最外层
offcanvas设height，否则会破坏动画定位逻辑 - 如果用了自定义 header（比如带关闭按钮的 bar），把它单独放在
offcanvas-header里，别混进offcanvas-body - 注意移动端 Safari 对
calc()和vh的兼容性：iOS 15+ 没问题，老版本建议用100dvh替代100vh
和 collapse 或 modal 混用时的冲突点
offcanvas 和 modal 共享同一套 backdrop 管理逻辑，同时打开会互相干扰；collapse 则可能因父容器 overflow: hidden 导致动画截断。
- 绝对不要在一个
offcanvas里再放一个modal——会触发两次 backdrop、键盘事件错乱、关闭后页面滚动锁死 - 如果侧边栏里有折叠菜单（比如用
collapse展开子项），确保它的父容器没有overflow: hidden，否则动画会被裁掉 - 想实现“侧边栏内嵌弹窗”，改用
offcanvas嵌套另一个offcanvas（Bootstrap 5.3+ 支持），但需手动管理z-index和关闭链 - 所有基于
data-bs-*触发的组件，都依赖 Bootstrap 的data-api自动初始化。禁用它（data-bs-auto-close="false"）后，必须手写 JS 控制开关
侧边栏抽屉看着简单，实际卡点都在 DOM 位置、z-index 层级和初始化时机上。尤其是动态渲染场景下，offcanvas 必须在 JS 执行前就存在于 body 中，这点容易被忽略。
