modal-dialog-centered 类必须加在 .modal-dialog 上，因其垂直居中依赖该元素的 top: 50% + transform: translate(-50%, -50%) 定位逻辑，而 .modal 和 .modal-content 不满足定位与变换条件。
Bootstrap 5 的 modal-dialog-centered 类为什么必须加在 .modal-dialog 上
因为 Bootstrap 5 的 Modal 垂直居中逻辑只作用于 .modal-dialog 元素——它内部用的是 top: 50% + transform: translate(-50%, -50%)，这个组合依赖该元素是相对/绝对定位上下文中的“可变换块级元素”。
如果加在 .modal 或 .modal-content 上，样式不会生效：.modal 默认是 display: block，不响应 transform；.modal-content 是子容器，没被设计为定位锚点。
- ✅ 正确结构：
<div class="modal-dialog modal-dialog-centered"><li>❌ 错误写法：<code><div class="modal modal-dialog-centered"> 或 <code><div class="modal-content modal-dialog-centered"> <li>⚠️ 如果用了 <code>fade动画，还要确认没覆盖.modal.fade .modal-dialog的margin-top，否则动画起始位置会偏移 - 长内容模态框可能被截断（
overflow: hidden对 flex 容器的子项裁剪不可控） - 移动端 Safari 下，键盘弹出时视口高度重算异常，导致模态框突然上移或消失
-
.modal-dialog的max-width响应式断点（如md、lg）可能失效，因为 flex 容器会强制子项收缩 - 与第三方插件（如
bootstrap-select或富文本编辑器）冲突概率上升 - ✅ 推荐做法：监听
shown.bs.modal事件，在内容渲染完成后再触发一次重定位（仅当内容高度明显变化时）：$('#myModal').on('shown.bs.modal', function () { const $dialog = $(this).find('.modal-dialog'); // 强制重绘，触发 transform 重计算 $dialog[0].offsetHeight; }); - ⚠️ 避免在
show.bs.modal中操作，此时 DOM 还未 append 到 body，尺寸读取为 0 - 别用
setTimeout等固定延迟，不同网络/设备下加载时间不稳定 - 若内容含图片，可监听
img.onload后再调用$dialog[0].offsetHeight触发重排 - 安全写法是避免依赖
min-height: 100vh—— 不要给.modal或.modal-dialog设定固定高度相关样式 - 如果项目需兼容 iOS 14，可加降级 JS 计算：
top = (window.innerHeight - $dialog.height()) / 2 + window.scrollY，但仅在检测到旧 Safari 时启用 - 不要用
calc(100vh - 60px)扣导航栏高度，iOS Safari 的vh在地址栏收起/展开时会跳变，造成抖动 - 测试时务必真机验证：模拟器无法复现 Safari 地址栏对视口高度的影响
为什么直接给 .modal 加 display: flex 不推荐
虽然手动补 .modal { display: flex; align-items: center; justify-content: center; } 看似能居中，但它会破坏 Bootstrap 5 原生的滚动行为和响应式逻辑。Modal 的 overflow: hidden 和 backdrop 渲染机制依赖 .modal 的默认 display: block 行为，改成 flex 后：
modal-dialog-centered 在动态内容加载后失效怎么办
典型场景：模态框打开时内容为空，再通过 AJAX 加载图片、CodeMirror 或视频组件，加载完成后高度突增，但 .modal-dialog 没重新计算位置——因为它只在初始化时靠 CSS transform 定位，不监听 DOM 尺寸变化。
移动端 Safari 和旧 Android WebView 的兼容细节
modal-dialog-centered 在 iOS 15+ 和 Android Chrome 80+ 上表现稳定，但在 iOS 14 及更早版本的 Safari 中，vh 单位和键盘弹出后的视口重算不准，会导致模态框偏高或被遮挡。
真正容易被忽略的是：modal-dialog-centered 的生效前提是 Modal 的 DOM 已挂载到 且未被其他 CSS 干扰定位上下文。比如外层有 position: fixed 的布局容器，或自定义主题重写了 .modal 的 z-index 和 position，都可能导致 transform 失效——这时候得先查 computed styles 里 .modal-dialog 的 position 是不是 absolute，以及它的 top 是否被覆盖成非 50%。
