Bootstrap 5模态框需严格遵循三层结构，推荐data-bs-toggle触发；Headless UI提供无样式可访问组件，需手动处理Backdrop和SSR延迟；手写fixed模态框易忽略焦点锁定、inert属性等无障碍细节。
用 Bootstrap 的 modal 类快速启动
Bootstrap 5 内置的模态框组件开箱即用，不需要写 JS 就能触发基础交互。关键在于结构必须严格遵循其约定：外层 div 带 class="modal"，内部有 modal-dialog 和 modal-content 三层嵌套。
触发方式有两种：data-bs-toggle="modal" + data-bs-target="#id"（推荐），或直接调用 bootstrap.Modal.getOrCreateInstance() 手动控制。注意 Bootstrap 5 已移除 jQuery 依赖，所有 JS 方法都走原生实例 API。
- 忘记加
tabindex="-1"到最外层modal容器，会导致键盘焦点异常 -
modal-backdrop默认是半透明黑底，若页面已有固定定位遮罩层，可能 z-index 冲突，需手动调高.modal的z-index - 响应式断点下
modal-dialog默认居中，但宽高不自适应内容，长文本或表单需额外加max-height: 80vh; overflow-y: auto;
Tailwind CSS 配合 Headless UI 实现无样式侵入
纯工具类框架本身不提供模态框逻辑，得靠第三方库补足。Headless UI 是最常用选择，它只提供可访问性完备的、无样式的 React / Vue 组件，样式完全由你用 class 控制。
以 React 版为例：Dialog 组件负责状态管理与焦点锁定，Dialog.Panel 是你自由写 Tailwind 类的地方。它自动处理 Esc 关闭、点击 backdrop 关闭、焦点环迁移等细节。
立即学习“前端免费学习笔记（深入）”；
- 别直接用
display: none控制显隐——Headless UI 依赖unmount或hidden属性做无障碍语义，应使用openprop 驱动 - Backdrop 背景需手动加
fixed inset-0 bg-black/50，且必须放在Dialog外层，否则会被 Portal 隔离导致 z-index 失效 - 服务端渲染（如 Next.js）中首次加载时可能出现“SSR 与 CSR 不一致”警告，需用
useState(false)+useEffect延迟挂载Dialog
避免手写 position: fixed 模态框的陷阱
自己用 CSS 定位 + visibility/opacity 控制显示，看似简单，实则容易漏掉关键可访问性和体验细节。
- 没加
inert属性或用aria-hidden="true"关闭背景内容，屏幕阅读器仍会朗读背后元素 - 未监听
keydown捕获Tab键并限制焦点在模态框内，用户按 Tab 可能跳出弹窗 - 没处理
body { overflow: hidden }，滚动模态框时页面主体仍可滚，造成双滚动条或错位 - 移动端 Safari 中，
position: fixed在键盘弹出后常失效，需监听resize或用transform: translateZ(0)强制硬件加速
小项目够用的轻量方案：@headlessui/react + 单文件封装
如果不想引入整套 UI 库，可以只装 @headlessui/react（约 8KB gzip），再封装一个 Modal 组件，把常见 props（isOpen, onClose, size）收口。
示例结构：
function Modal({ isOpen, onClose, children, size = "md" }) {
return (
);
}
这个封装屏蔽了大部分底层细节，但保留了 Tailwind 的定制自由度。真正容易被忽略的是：Transition 动画必须包裹在 Dialog 外层，否则 enter/leave 类不会生效；且 size 参数要和 Tailwind 的 max-w- 前缀严格对应，不然会编译失败。
