BOOTSTRA.386 复古主题下的 Bootstrap 5.3 Modal 组件全解析:从 data 属性到源码级原理
BOOTSTRA.386 复古主题下的 Bootstrap 5.3 Modal 组件全解析:从 data 属性到源码级原理
本文以 BOOTSTRA.386 仓库中 Bootstrap 5.3 的 Modal 组件官方文档(modal.md)为核心,结合仓库内真实源码(modal.js、_modal.scss、_variables.scss)与单元测试(modal.spec.js),系统讲解模态框的搭建、动画、尺寸、全屏模式、可访问性与编程式 API。读完本文,你将掌握在 1980s DOS 风格主题下快速落地"可用、可测、可定制"模态框的完整实战方案,并能理解其背后的滚动锁定、焦点陷阱、Backdrop 生成等底层机制。
工作原理:Modal 的三大基石与设计约束
在开始使用 Bootstrap 5.3 的 modal 组件之前,需要先明确它的几个核心设计前提(官方文档明确列出,近期菜单选项亦有所调整):
- HTML、CSS、JavaScript 三合一:模态框由三者共同构建。它被定位在文档中所有其他元素之上,并通过移除
<body>的滚动,让模态内容自身滚动(对应源码 modal.js 中this._scrollBar.hide()与document.body.classList.add(CLASS_NAME_OPEN),body 会获得.modal-open类来"杀死"滚动)。 - 点击 backdrop 自动关闭:点击模态框半透明遮罩即可关闭,无需额外代码。
- 同一时刻只支持一个模态框:Bootstrap 不支持嵌套模态,官方认为嵌套会带来糟糕的用户体验。源码中也有对应保障:Data API 在触发新模态前会先查找已打开的模态并将其隐藏(见 modal.js)。
position: fixed的渲染注意点:模态使用固定定位,对渲染环境比较敏感。应尽量把模态 HTML 放在页面顶层位置,避免与其他固定定位元素相互干扰;把.modal嵌套在另一个position: fixed元素内很可能出问题。- 移动端限制:同样是
position: fixed带来的问题,移动设备上使用模态存在一些注意事项,详见仓库内 browsers-devices.md("Modals and dropdowns on mobile" 一节)。 autofocus属性无效:由于 HTML5 语义定义,autofocus在 Bootstrap 模态中不生效。要实现打开即聚焦的效果,需要借助shown.bs.modal事件配合自定义 JavaScript:
const myModal = document.getElementById('myModal')
const myInput = document.getElementById('myInput')
myModal.addEventListener('shown.bs.modal', () => {
myInput.focus()
})
- 减少动效偏好:官方建议考虑用户的
prefers-reduced-motion设置(文档中以 callout 形式提示,内容详见仓库v5.3.1/site/content/docs/5.3下的相关说明)。
基础示例
静态示例与组件结构
下面是一个静态 modal 示例(其 position 与 display 被覆盖以用于文档展示),包含模态头部(header)、模态主体(body,必填,用于提供 padding)和模态底部(footer,可选)。官方建议:尽可能为模态头提供关闭按钮,或提供其他明确的关闭操作。
<div class="modal" tabindex="-1">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Modal title</h5>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>Modal body text goes here.</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Save changes</button>
</div>
</div>
</div>
</div>
结构层次为:.modal(容器,负责滚动)→ .modal-dialog(定位外壳)→ .modal-content(真实内容,带背景与圆角),这与 _modal.scss 文件头部的注释完全一致:
// .modal-open - body class for killing the scroll
// .modal - container to scroll within
// .modal-dialog - positioning shell for the actual modal
// .modal-content - actual modal w/ bg and corners and stuff
一个小细节:上述静态示例中使用 <h5> 是为了避免打乱文档页面的标题层级。但从结构上讲,模态对话框代表一个独立的文档/上下文,.modal-title 理想情况下应该是 <h1>。若需要调整外观,可以使用字号工具类(见仓库内 text.md 的 "font size" 部分)。本文后续所有真实示例都采用这种 <h1 class="modal-title fs-5"> 写法。
Live demo:通过 data 属性一键触发
触发按钮与模态本体通过 data-bs-toggle="modal" 与 data-bs-target="#exampleModal" 关联:
<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal">
Launch demo modal
</button>
<!-- Modal -->
<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalLabel">Modal title</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Save changes</button>
</div>
</div>
</div>
</div>
加上 .fade 类后,模态会从页面顶部滑入并淡入显示。动画背后的 transform 状态来自两个 Sass 变量:$modal-fade-transform(进入动画前)与 $modal-show-transform(进入动画结束后),见 _variables.scss:
$modal-fade-transform: translate(0, -50px) !default;
$modal-show-transform: none !default;
$modal-transition: transform .3s ease-out !default;
$modal-scale-transform: scale(1.02) !default;
Static backdrop:阻止点击外部关闭
当 backdrop 设为 static 时,点击模态外部不会关闭模态;同时把 data-bs-keyboard="false" 可禁用 Esc 键关闭:
<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#staticBackdrop">
Launch static backdrop modal
</button>
<!-- Modal -->
<div class="modal fade" id="staticBackdrop" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="staticBackdropLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="staticBackdropLabel">Modal title</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Understood</button>
</div>
</div>
</div>
</div>
点击 backdrop 与按 Esc 时,modal 会先轻微"抖动"(通过 .modal-static 类与 $modal-scale-transform: scale(1.02) 实现"试图缩放"的反馈效果),并触发 hidePrevented.bs.modal 事件。这条逻辑完整落在 modal.js 的 _triggerBackdropTransition() 方法中:先触发 hidePrevented.bs.modal 事件,若未被 defaultPrevented,则给元素加上 .modal-static 类,动画结束后移除并恢复 overflowY。
滚动长内容与 modal-dialog-scrollable
当模态内容超出视口高度时,它会独立于页面自身滚动。官方演示中通过给 .modal-body 设置 style="min-height: 1500px" 来拉长内容以展示溢出滚动。
更常用的做法是给 .modal-dialog 追加 .modal-dialog-scrollable,让模态主体内部滚动(头部与底部固定):
<!-- Scrollable modal -->
<div class="modal-dialog modal-dialog-scrollable">
...
</div>
其 CSS 实现位于 _modal.scss:.modal-dialog-scrollable 计算 height: calc(100% - modal-margin * 2),让 .modal-content 的 max-height 为 100% 并 overflow: hidden,最终由 .modal-body 承担 overflow-y: auto 的内滚任务。
垂直居中
给 .modal-dialog 追加 .modal-dialog-centered 即可实现垂直居中;它与 .modal-dialog-scrollable 可以组合使用:
<!-- Vertically centered modal -->
<div class="modal-dialog modal-dialog-centered">
...
</div>
<!-- Vertically centered scrollable modal -->
<div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
...
</div>
实现上,_modal.scss 使用 flexbox:display: flex; align-items: center; min-height: calc(100% - var(--bs-modal-margin) * 2)。
模态内的 Tooltip 与 Popover
Tooltip 和 Popover 可以按需放进模态中;当模态关闭时,其内部的 tooltip 与 popover 也会被自动销毁。在模态内使用这两个组件时,务必通过 data-bs-container 指定容器为模态本身,防止 tooltip/popover 被模态的溢出裁剪:
<div class="modal-body">
<h2 class="fs-5">Popover in a modal</h2>
<p>This <button class="btn btn-secondary" data-bs-toggle="popover" title="Popover title" data-bs-content="Popover body content is set in this attribute.">button</button> triggers a popover on click.</p>
<hr>
<h2 class="fs-5">Tooltips in a modal</h2>
<p><a href="#" data-bs-toggle="tooltip" title="Tooltip">This link</a> and <a href="#" data-bs-toggle="tooltip" title="Tooltip">that link</a> have tooltips on hover.</p>
</div>
Tooltip 与 Popover 的完整用法可分别参考仓库内 tooltips.md 与 popovers.md。
在 Modal 中使用栅格系统
在 .modal-body 内嵌套一个 .container-fluid,即可像在页面其他位置一样使用 Bootstrap 栅格类(支持多行、自动边距、嵌套列等):
<div class="modal-body">
<div class="container-fluid">
<div class="row">
<div class="col-md-4">.col-md-4</div>
<div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div>
</div>
<div class="row">
<div class="col-md-3 ms-auto">.col-md-3 .ms-auto</div>
<div class="col-md-2 ms-auto">.col-md-2 .ms-auto</div>
</div>
<div class="row">
<div class="col-md-6 ms-auto">.col-md-6 .ms-auto</div>
</div>
<div class="row">
<div class="col-sm-9">
Level 1: .col-sm-9
<div class="row">
<div class="col-8 col-sm-6">
Level 2: .col-8 .col-sm-6
</div>
<div class="col-4 col-sm-6">
Level 2: .col-4 .col-sm-6
</div>
</div>
</div>
</div>
</div>
</div>
Varying modal content:按触发按钮动态改变内容
当多个按钮触发同一个模态、但各自内容不同时,利用 event.relatedTarget 与 HTML data-bs-* 属性即可动态填充。原理:show.bs.modal 事件触发时,事件对象上的 relatedTarget 指向触发该模态的按钮元素,读取按钮上的自定义 data 属性后写入模态内容。
三个按钮分别携带 data-bs-whatever 数据:
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@mdo">Open modal for @mdo</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@fat">Open modal for @fat</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@getbootstrap">Open modal for @getbootstrap</button>
<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalLabel">New message</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<form>
<div class="mb-3">
<label for="recipient-name" class="col-form-label">Recipient:</label>
<input type="text" class="form-control" id="recipient-name">
</div>
<div class="mb-3">
<label for="message-text" class="col-form-label">Message:</label>
<textarea class="form-control" id="message-text"></textarea>
</div>
</form>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Send message</button>
</div>
</div>
</div>
</div>
对应 JavaScript(该示例的真实实现就写在仓库 snippets.js 中,可直接对照学习):
const exampleModal = document.getElementById('exampleModal')
if (exampleModal) {
exampleModal.addEventListener('show.bs.modal', event => {
// Button that triggered the modal
const button = event.relatedTarget
// Extract info from data-bs-* attributes
const recipient = button.getAttribute('data-bs-whatever')
// If necessary, you could initiate an Ajax request here
// and then do the updating in a callback.
// Update the modal's content.
const modalTitle = exampleModal.querySelector('.modal-title')
const modalBodyInput = exampleModal.querySelector('.modal-body input')
modalTitle.textContent = `New message to ${recipient}`
modalBodyInput.value = recipient
})
}
show.bs.modal 事件的 relatedTarget 细节可参见下文"事件"一节。
模态间切换(Toggle between modals)
通过巧妙布置 data-bs-target 与 data-bs-toggle 属性,可以在两个模态之间来回切换(例如从已打开的登录模态里唤起密码重置模态)。注意:同一时刻不能同时打开多个模态,此方法只是在两个独立的模态之间做切换:
<div class="modal fade" id="exampleModalToggle" aria-hidden="true" aria-labelledby="exampleModalToggleLabel" tabindex="-1">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalToggleLabel">Modal 1</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
Show a second modal and hide this one with the button below.
</div>
<div class="modal-footer">
<button class="btn btn-primary" data-bs-target="#exampleModalToggle2" data-bs-toggle="modal">Open second modal</button>
</div>
</div>
</div>
</div>
<div class="modal fade" id="exampleModalToggle2" aria-hidden="true" aria-labelledby="exampleModalToggleLabel2" tabindex="-1">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h1 class="modal-title fs-5" id="exampleModalToggleLabel2">Modal 2</h1>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
Hide this modal and show the first with the button below.
</div>
<div class="modal-footer">
<button class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">Back to first</button>
</div>
</div>
</div>
</div>
<button class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">Open first modal</button>
动画定制与移除
- 定制进入动画:
$modal-fade-transform决定.modal-dialog在淡入动画开始前的 transform 状态,$modal-show-transform决定动画结束后的 transform 状态。例如想要缩放进入效果,把$modal-fade-transform设为scale(.8)即可(变量定义位置)。 - 移除动画:若希望模态直接出现而不淡入,去掉
.fade类即可:
<div class="modal" tabindex="-1" aria-labelledby="..." aria-hidden="true">
...
</div>
动态高度与 handleUpdate
如果模态打开期间其高度发生变化(例如内容异步加载后出现滚动条),应调用 myModal.handleUpdate() 重新调整模态位置。其底层调用的是 _adjustDialog()(modal.js),该方法会比较模态滚动高度与视口高度、测量滚动条宽度,并据此在左右两侧补充/移除内边距以抵消滚动条出现带来的偏移(见 modal.js)。窗口 resize 时源码也会自动执行同样的调整(modal.js)。
可访问性
务必在 .modal 上添加 aria-labelledby="..." 并指向模态标题;也可以通过 aria-describedby 提供模态对话框的描述。不需要手写 role="dialog"——它由 JavaScript 自动添加(见 modal.js:this._element.setAttribute('role', 'dialog'))。
此外,模态显示时源码会自动补充 aria-modal="true"(modal.js),隐藏时移除 aria-modal 与 role 并恢复 aria-hidden="true"(modal.js),这些细节保证了模态的生命周期符合无障碍规范。
嵌入 YouTube 视频
在模态中嵌入 YouTube 视频需要额外的 JavaScript(Bootstrap 本身不包含自动停止播放等逻辑)。官方文档提示可以参考社区方案自行实现(此类功能依赖第三方脚本,无法在此仓库内直接验证)。
可选尺寸
模态提供三种可选尺寸,通过在 .modal-dialog 上追加修饰类实现。这些尺寸在特定断点处生效,以避免窄视口下出现横向滚动条:
| 尺寸 | 类名 | 模态最大宽度 |
|---|---|---|
| Small | .modal-sm |
300px |
| 默认 | 无(相当于 Medium) | 500px |
| Large | .modal-lg |
800px |
| Extra large | .modal-xl |
1140px |
<div class="modal-dialog modal-xl">...</div>
<div class="modal-dialog modal-lg">...</div>
<div class="modal-dialog modal-sm">...</div>
数值来源见 _variables.scss($modal-sm: 300px、$modal-md: 500px、$modal-lg: 800px、$modal-xl: 1140px)。响应式生效逻辑在 _modal.scss:从 sm 断点起,.modal-dialog 获得 max-width: var(--bs-modal-width) 并水平居中;.modal-sm 在 sm 起生效、.modal-lg/.modal-xl 在 lg 起生效、.modal-xl 在 xl 起扩展为 1140px——宽度实际是通过覆盖 CSS 变量 --bs-modal-width 实现的。
全屏 Modal
另一个覆盖模式是弹出铺满视口的模态,同样通过在 .modal-dialog 上追加修饰类实现:
| 类名 | 可用性 |
|---|---|
.modal-fullscreen |
始终 |
.modal-fullscreen-sm-down |
576px 以下 |
.modal-fullscreen-md-down |
768px 以下 |
.modal-fullscreen-lg-down |
992px 以下 |
.modal-fullscreen-xl-down |
1200px 以下 |
.modal-fullscreen-xxl-down |
1400px 以下 |
<!-- Full screen modal -->
<div class="modal-dialog modal-fullscreen-sm-down">
...
</div>
这些响应式全屏类是通过 Sass 循环自动生成的:源码遍历 $grid-breakpoints 中的每个断点,用 breakpoint-infix 拼出 -sm-down 等后缀,再在 media-breakpoint-down 内输出对应规则(见 _modal.scss 中 modal-fullscreen-loop 注释包裹的 @each 循环)。生成的规则让 .modal-fullscreen* 在目标断点以下 width: 100vw; max-width: none; height: 100%; margin: 0,同时去掉 .modal-content 的边框与圆角、让 .modal-body 负责 overflow-y: auto。
CSS 变量与 Sass 定制(源码级)
CSS 变量(自 5.2.0 引入)
作为 Bootstrap 不断演进 CSS 变量方案的组成部分,modal 现在在 .modal 与 .modal-backdrop 上使用局部 CSS 变量,支持实时定制;变量值由 Sass 注入,因此 Sass 定制依然完全可用。
.modal 上的变量(定义见 _modal.scss):
--#{$prefix}modal-zindex: #{$zindex-modal};
--#{$prefix}modal-width: #{$modal-md};
--#{$prefix}modal-padding: #{$modal-inner-padding};
--#{$prefix}modal-margin: #{$modal-dialog-margin};
--#{$prefix}modal-color: #{$modal-content-color};
--#{$prefix}modal-bg: #{$modal-content-bg};
--#{$prefix}modal-border-color: #{$modal-content-border-color};
--#{$prefix}modal-border-width: #{$modal-content-border-width};
--#{$prefix}modal-border-radius: #{$modal-content-border-radius};
--#{$prefix}modal-box-shadow: #{$modal-content-box-shadow-xs};
--#{$prefix}modal-inner-border-radius: #{$modal-content-inner-border-radius};
--#{$prefix}modal-header-padding-x: #{$modal-header-padding-x};
--#{$prefix}modal-header-padding-y: #{$modal-header-padding-y};
--#{$prefix}modal-header-padding: #{$modal-header-padding};
--#{$prefix}modal-header-border-color: #{$modal-header-border-color};
--#{$prefix}modal-header-border-width: #{$modal-header-border-width};
--#{$prefix}modal-title-line-height: #{$modal-title-line-height};
--#{$prefix}modal-footer-gap: #{$modal-footer-margin-between};
--#{$prefix}modal-footer-bg: #{$modal-footer-bg};
--#{$prefix}modal-footer-border-color: #{$modal-footer-border-color};
--#{$prefix}modal-footer-border-width: #{$modal-footer-border-width};
.modal-backdrop 上的变量(见 _modal.scss):
--#{$prefix}backdrop-zindex: #{$zindex-modal-backdrop};
--#{$prefix}backdrop-bg: #{$modal-backdrop-bg};
--#{$prefix}backdrop-opacity: #{$modal-backdrop-opacity};
$zindex-modal-backdrop: 1050 与 $zindex-modal: 1055 的定义位于 _variables.scss,backdrop 比模态低 5 层,确保模态始终浮于遮罩之上。
Sass 变量
Modal 的完整 Sass 变量清单位于 _variables.scss 的 modal-variables 区块,除上述 CSS 变量对应项外,还包括:
$modal-inner-padding: $spacer !default;
$modal-footer-margin-between: .5rem !default;
$modal-dialog-margin: .5rem !default;
$modal-dialog-margin-y-sm-up: 1.75rem !default;
$modal-title-line-height: $line-height-base !default;
$modal-content-color: null !default;
$modal-content-bg: var(--#{$prefix}body-bg) !default;
$modal-content-border-color: var(--#{$prefix}border-color-translucent) !default;
$modal-content-border-width: var(--#{$prefix}border-width) !default;
$modal-content-border-radius: var(--#{$prefix}border-radius-lg) !default;
$modal-content-inner-border-radius: subtract($modal-content-border-radius, $modal-content-border-width) !default;
$modal-content-box-shadow-xs: $box-shadow-sm !default;
$modal-content-box-shadow-sm-up: $box-shadow !default;
$modal-backdrop-bg: $black !default;
$modal-backdrop-opacity: .5 !default;
$modal-header-border-color: var(--#{$prefix}border-color) !default;
$modal-header-border-width: $modal-content-border-width !default;
$modal-header-padding-y: $modal-inner-padding !default;
$modal-header-padding-x: $modal-inner-padding !default;
$modal-header-padding: $modal-header-padding-y $modal-header-padding-x !default;
$modal-footer-bg: null !default;
$modal-footer-border-color: $modal-header-border-color !default;
$modal-footer-border-width: $modal-header-border-width !default;
$modal-sm: 300px !default;
$modal-md: 500px !default;
$modal-lg: 800px !default;
$modal-xl: 1140px !default;
$modal-fade-transform: translate(0, -50px) !default;
$modal-show-transform: none !default;
$modal-transition: transform .3s ease-out !default;
$modal-scale-transform: scale(1.02) !default;
Sass 循环
响应式全屏模态由 $breakpoints 映射配合 _modal.scss 中的 modal-fullscreen-loop 循环生成(上文"全屏 Modal"一节已详述)。
用法(Usage)
Modal 插件按需切换隐藏内容,可通过 data 属性或 JavaScript 驱动;它同时覆盖默认滚动行为,并生成一个 .modal-backdrop 提供点击关闭区域。
通过数据属性
触发(Toggle):无需编写 JavaScript,在控制器元素(如按钮)上设置 data-bs-toggle="modal",并配合 data-bs-target="#foo" 或 href="#foo" 指向目标模态:
<button type="button" data-bs-toggle="modal" data-bs-target="#myModal">Launch modal</button>
关闭(Dismiss):data-bs-dismiss="modal" 可用在被触发元素的内部(如关闭按钮、.btn-close)或外部。其底层由 modal.js 的 enableDismissTrigger(Modal) 统一注册——该工具函数会自动为所有 [data-bs-dismiss="modal"] 元素绑定点击事件,触发对应模态的 hide()。
官方同时给出提示:从模态外部关闭它不符合 WAI-ARIA 对话框(模态)模式的建议,请自行权衡风险。
通过 JavaScript
一行代码即可创建模态实例:
const myModal = new bootstrap.Modal(document.getElementById('myModal'), options)
// or
const myModalAlternative = new bootstrap.Modal('#myModal', options)
实例化时,构造函数会执行一系列初始化(modal.js):通过 SelectorEngine.findOne 找到 .modal-dialog、初始化 Backdrop 与 FocusTrap、创建 ScrollBarHelper 并注册事件监听器。
选项(Options)
通过 data 属性传参时,backdrop 的特殊取值 'static' 需要写成 data-bs-backdrop="static";其余布尔型选项直接写 data-bs-keyboard="false" 这类形式即可。选项也可以在 JavaScript 实例化时以对象传入。
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
backdrop |
boolean、'static' |
true |
是否包含 modal-backdrop 元素。设为 static 时,点击 backdrop 不会关闭模态 |
focus |
boolean | true |
初始化时是否将焦点放到模态上 |
keyboard |
boolean | true |
按下 Esc 键时是否关闭模态 |
这些默认值在源码中有精确对应(modal.js):
const Default = {
backdrop: true,
focus: true,
keyboard: true
}
方法(Methods)
官方特别提醒:异步方法(如 show、hide、toggle)在模态真正完成显示/隐藏之前就会返回(即在 shown.bs.modal / hidden.bs.modal 事件发生之前返回调用者)。若要在显示/隐藏完成后执行逻辑,应监听对应事件。
传入选项实例化:
const myModal = new bootstrap.Modal('#myModal', {
keyboard: false
})
| 方法 | 描述 |
|---|---|
dispose |
销毁元素上的模态实例(移除 DOM 元素上存储的数据) |
getInstance |
静态方法,获取与 DOM 元素关联的模态实例 |
getOrCreateInstance |
静态方法,获取与 DOM 元素关联的模态实例;若尚未初始化则创建一个 |
handleUpdate |
手动重新调整模态位置(模态打开期间高度变化、可能出现滚动条时使用) |
hide |
手动隐藏模态。在模态真正隐藏前即返回(即 hidden.bs.modal 事件发生前) |
show |
手动打开模态。在模态真正显示前即返回(即 shown.bs.modal 事件发生前)。可传入一个 DOM 元素作为参数,该元素会作为 relatedTarget 出现在模态事件中(如 const modalToggle = document.getElementById('toggleMyModal'); myModal.show(modalToggle)) |
toggle |
手动切换模态的显示/隐藏。在模态真正显示或隐藏前即返回(即 shown.bs.modal 或 hidden.bs.modal 事件发生前) |
从源码看,show(relatedTarget)(modal.js)的完整流程是:触发 show.bs.modal 事件(可被 preventDefault 取消)→ 隐藏页面滚动条 → 给 body 加 .modal-open → _adjustDialog() 处理溢出 → 显示 backdrop → 回调中执行 _showElement()(追加到 body、display: block、设置 aria-modal/role、重置滚动位置、触发 reflow、加 .show 类、激活焦点陷阱、触发 shown.bs.modal)。hide()(modal.js)则是对称流程:触发 hide.bs.modal → 停用焦点陷阱 → 移除 .show → 等待过渡结束后隐藏 backdrop、移除 .modal-open、重置滚动条与内边距、触发 hidden.bs.modal。
事件(Events)
Modal 类暴露了若干事件用于接入钩子。所有模态事件都触发在模态自身(即 <div class="modal"> 上):
| 事件 | 描述 |
|---|---|
hide.bs.modal |
hide 实例方法被调用时立即触发 |
hidden.bs.modal |
模态完全隐藏后触发(会等待 CSS 过渡完成) |
hidePrevented.bs.modal |
模态已显示、backdrop 为 static 且点击模态外部时触发;当 keyboard 为 false 且按下 Esc 时也会触发 |
show.bs.modal |
show 实例方法被调用时立即触发。若由点击引起,被点击的元素可作为事件的 relatedTarget 属性获取 |
shown.bs.modal |
模态对用户可见后触发(会等待 CSS 过渡完成)。若由点击引起,被点击的元素可作为事件的 relatedTarget 属性获取 |
监听示例:
const myModalEl = document.getElementById('myModal')
myModalEl.addEventListener('hidden.bs.modal', event => {
// do something...
})
事件常量在源码中定义为 EVENT_HIDE、EVENT_HIDE_PREVENTED、EVENT_HIDDEN、EVENT_SHOW、EVENT_SHOWN 等(modal.js),命名空间为 bs.modal。
源码级原理深挖:组件间的协作
围绕 modal 组件,仓库中还沉淀了三个重要协作单元,理解它们能帮你更精准地排查问题:
- Backdrop(遮罩):backdrop.js 是一个可复用的通用工具类。Modal 实例化时通过
_initializeBackDrop()(modal.js)传入isVisible: Boolean(this._config.backdrop)与isAnimated: this._isAnimated()。注意:backdrop: 'static'会被转为布尔真值,因此静态遮罩同样渲染;backdrop: false时 Backdrop 工具类不向 DOM 追加任何元素。遮罩的 className 固定为modal-backdrop,若模态带.fade类,遮罩也会获得.fade类以同步动画。 - FocusTrap(焦点陷阱):focustrap.js 确保键盘 Tab 焦点在模态打开期间被限制在模态内部。它在
document上监听focusin与keydown.tab:当焦点试图逃出trapElement(即模态元素)时,会把焦点拉回模态内第一个(或按 Shift+Tab 时的最后一个)可聚焦子元素;若模态内没有任何可聚焦元素,则直接聚焦模态自身(focustrap.js)。这就是focus: true选项与良好键盘可达性的来源。 - ScrollBarHelper(滚动条处理):模态打开时隐藏
body滚动、关闭时恢复,同时_adjustDialog()会测量滚动条宽度并在模态上补偿内边距,避免页面滚动条消失导致的"跳动"。
仓库自带的单元测试 modal.spec.js 覆盖了 toggle、show、hide、dispose、handleUpdate、data-api、jQueryInterface、getInstance/getOrCreateInstance 等全部公开 API,并验证了 backdrop: 'static'、keyboard: false 等选项组合下的行为(如 hidePrevented 相关场景),是理解组件契约的第一手资料。若你基于源码做了定制,跑一遍这些测试即可快速回归验证。
在 BOOTSTRA.386 DOS 复古主题下的使用建议
BOOTSTRA.386 是"让网页看起来来自 1980 年代"的 Bootstrap 主题(仓库 README 明确说明其覆盖 Bootstrap v2/3/4/5,v5 仍在进行中)。在该主题下使用 Modal 组件时,有几个来自源码的细节值得注意:
- 层级关系:主题的 DOS 光标元素
.bootstra-cursor设置了z-index: 20000(见 _dos.scss),而 modal 的$zindex-modal-backdrop: 1050、$zindex-modal: 1055远低于它。从源码结构看,若同时启用了.bootstra-enable-cursor(该模式下cursor: none !important会隐藏系统鼠标),DOS 风格的方块光标会显示在模态之上,营造"复古终端里弹窗"的效果,但如果你希望光标被模态遮挡,需要自行提高模态的 z-index。 - 滚动条风格:主题通过
*::-webkit-scrollbar系列规则(_dos.scss)将 WebKit 滚动条绘制为黑底点阵风格,因此.modal-body内部滚动与.modal-dialog-scrollable的滚动条会自动继承这套 DOS 视觉,无需额外处理。 - 建议先验证视觉效果:由于 v5 主题尚在进行中,建议在引入 modal 后重点检查 backdrop 透明度、边框圆角与阴影在 DOS 点阵配色下的观感——这些均可用上文介绍的 CSS 变量(如
--bs-modal-bg、--bs-modal-border-color、--bs-modal-box-shadow)或 Sass 变量在构建期快速调整。
小结
Bootstrap 5.3 的 Modal 组件以 .modal → .modal-dialog → .modal-content 三层结构为骨架,通过 data-bs-toggle / data-bs-target / data-bs-dismiss 即可零 JS 使用,配合 .modal-dialog-scrollable、.modal-dialog-centered、尺寸类与全屏类覆盖绝大多数布局诉求;其背后是 modal.js 对滚动锁定、焦点陷阱、遮罩生命周期与五个事件的精细管理。结合 BOOTSTRA.386 的 DOS 主题,你可以在保持复古视觉一致性的前提下,安全地使用 CSS 变量与 Sass 变量做实时定制,并通过仓库内的测试用例(modal.spec.js)与文档示例(modal.md、snippets.js)快速验证与二次开发。