BOOTSTRA.386 复古主题下的 Bootstrap 5.3 Modal 组件全解析:从 data 属性到源码级原理

原创2026-10-14 13:47:511,739 阅读
文章标签:前端UI组件

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 组件,仓库中还沉淀了三个重要协作单元,理解它们能帮你更精准地排查问题:

  1. 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 类以同步动画。
  2. FocusTrap(焦点陷阱):focustrap.js 确保键盘 Tab 焦点在模态打开期间被限制在模态内部。它在 document 上监听 focusin 与 keydown.tab:当焦点试图逃出 trapElement(即模态元素)时,会把焦点拉回模态内第一个(或按 Shift+Tab 时的最后一个)可聚焦子元素;若模态内没有任何可聚焦元素,则直接聚焦模态自身(focustrap.js)。这就是 focus: true 选项与良好键盘可达性的来源。
  3. 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)快速验证与二次开发。

登录后查看全文
BOOTSTRA.386