模态框

使用 Bootstrap 的 JavaScript 模态插件向您的站点添加对话框,用于灯箱、用户通知或完全自定义的内容。

它是怎样工作的

在开始使用 Bootstrap 的模态组件之前,请务必阅读以下内容,因为我们的菜单选项最近发生了变化。

  • 模态框是用 HTML、CSS 和 JavaScript 构建的。 它们被定位在文档中的所有其他内容之上,并从 <body> 中移除滚动,以便模态框内容滚动。
  • 点击模态 “背景” 将自动关闭模态框。
  • Bootstrap 一次只支持一个模态窗口。不支持嵌套模式,因为我们认为它们是糟糕的用户体验。
  • 模态框使用 position:fixed,它的渲染有时会有些特殊。只要有可能,将您的模态 HTML 放在顶级位置,以避免来自其他元素的潜在干扰。 将 .modal 嵌套在另一个固定元素中时,您可能会遇到问题。
  • 再一次,由于 position:fixed,在移动设备上使用模态框有一些注意事项。
  • 由于 HTML5 如何定义其语义,autofocus HTML 属性 在 Bootstrap 模式中无效。要达到相同的效果,请使用一些自定义 JavaScript:
var myModal = document.getElementById('myModal')
      var myInput = document.getElementById('myInput')

      myModal.addEventListener('shown.bs.modal', function () {
        myInput.focus()
      })
该组件的动画效果依赖于 prefers-reduced-motion 媒体查询。

继续阅读演示和使用指南。

示例
模态组件

下面是一个 static 模态示例(意味着它的 positiondisplay 已被覆盖)。 包括模态标题、模态正文(padding 必需)和模态页脚(可选)。 我们要求您尽可能在模式标题中包含解除操作,或提供另一个明确的解除操作。

<div class="modal" tabindex="-1">
        <div class="modal-dialog">
          <div class="modal-content">
            <div class="modal-header">
              <h6 class="modal-title">标题</h6>
              <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
            </div>
            <div class="modal-body">
              <p>祷罢,试卜一爻,暗视道:“我李靖若有天子之分,乞即赐一圣爻。”将爻掷下。</p>
            </div>
            <div class="modal-footer">
              <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">关闭</button>
              <button type="button" class="btn btn-primary">保存修改</button>
            </div>
          </div>
        </div>
      </div>
现场示例

通过单击下面的按钮来切换工作模式演示。它将向下滑动并从页面顶部淡入。

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModalLive">
        启动演示模态框
      </button>

      <div class="modal fade" id="exampleModalLive" tabindex="-1" aria-labelledby="exampleModalLiveLabel" aria-hidden="true">
        <div class="modal-dialog">
          <div class="modal-content">
            <div class="modal-header">
              <h6 class="modal-title" id="exampleModalLiveLabel">二心集</h6>
              <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
            </div>
            <div class="modal-body">
              <p>杂文集,收录了鲁迅在1930年-1931年间所写的杂文三十七篇。</p>
            </div>
            <div class="modal-footer">
              <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">关闭</button>
              <button type="button" class="btn btn-primary">保存修改</button>
            </div>
          </div>
        </div>
      </div>
静态背景

当背景设置为静态时,在其外部单击时模态将不会关闭。单击下面的按钮进行尝试。

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#staticBackdropLive">
        启动静态背景模态框
      </button>

      <div class="modal fade" id="staticBackdropLive" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="staticBackdropLiveLabel" aria-hidden="true">
        <div class="modal-dialog">
          <div class="modal-content">
            <div class="modal-header">
              <h6 class="modal-title" id="staticBackdropLiveLabel">东游记</h6>
              <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
            </div>
            <div class="modal-body">
              <p>又名《上洞八仙传》、《八仙出处东游记》,共二卷五十六回。记叙铁拐李、汉钟离、吕洞宾、张果老、蓝采和、何仙姑、韩湘子、曹国舅八位神仙修炼得道的过程。</p>
            </div>
            <div class="modal-footer">
              <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">关闭</button>
              <button type="button" class="btn btn-primary">明白了</button>
            </div>
          </div>
        </div>
      </div>
滚动长内容

当模态框对于用户的视口或设备而言变得太长时,它们会独立于页面本身滚动。试试下面的演示,看看我们的意思。

您还可以通过将 .modal-dialog-scrollable 添加到 .modal-dialog 来创建允许滚动模态体的可滚动模态。

<!-- 可滚动模态框 -->
      <div class="modal-dialog modal-dialog-scrollable">
        ...
      </div>
垂直居中

.modal-dialog-centered 添加到 .modal-dialog 以使模态框垂直居中。

<!-- 垂直居中的模态框 -->
      <div class="modal-dialog modal-dialog-centered">
        ...
      </div>

      <!-- 垂直居中的可滚动模态框 -->
      <div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
        ...
      </div>
工具提示和弹出框

工具提示和弹出框可以根据需要放置在模态框中。当模态框关闭时,其中的任何工具提示和弹出框也会自动关闭。

<div class="modal-body">
        <h5>模态框中的Popover</h5>
        <p>与<a href="#" role="button" class="btn btn-secondary" title="万花楼演义" data-bs-content="又名《万花楼杨包狄演义》,十四卷六十八回。" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right">《万花楼演义》</a>同脉络,但情节内容自成首尾,叙述宋仁宗命狄青等五虎将征西的故事。</p>
        <hr>
        <h5>模态框中的Tooltips</h5>
        <p>作者依照时代的人心需要,创造了<a href="#" title="字汉臣,北宋名将" data-bs-container="#exampleModalPopovers" data-bs-toggle="tooltip" data-bs-placement="top">狄青</a>和<a href="#" title="字希仁,北宋名臣" data-bs-container="#exampleModalPopovers" data-bs-toggle="tooltip" data-bs-placement="top">包公</a>等符合人们愿望的人物,托名历史而演述出一系列故事。</p>
      </div>
使用网格

通过将 .container-fluid 嵌套在 .modal-body 中,在 modal 中使用 Bootstrap 网格系统。然后,像在其他任何地方一样使用普通的网格系统类。

<div class="modal-body">
        <div class="container-fluid bd-example-row">
          <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>
改变模态框内容

有一堆按钮都触发相同的模式,内容略有不同?使用 event.relatedTargetHTML data-bs-* 属性 以根据单击的按钮来改变模式的内容。

下面是一个现场演示,后面是示例 HTML 和 JavaScript。如需更多信息,请阅读模态事框件文档以了解有关 relatedTarget 的详细信息。

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@mdo">打开模态 @mdo</button>
      <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@fat">打开模态框 @fat</button>
      <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@getbootstrap">打开模态框 @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">
              <h6 class="modal-title" id="exampleModalLabel">新消息</h6>
              <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">收件人:</label>
                  <input type="text" class="form-control" id="recipient-name">
                </div>
                <div class="mb-3">
                  <label for="message-text" class="col-form-label">消息:</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">关闭</button>
              <button type="button" class="btn btn-primary">发送消息</button>
            </div>
          </div>
        </div>
      </div>
var exampleModal = document.getElementById('exampleModal')
      exampleModal.addEventListener('show.bs.modal', function (event) {
        // Button that triggered the modal
        var button = event.relatedTarget
        // Extract info from data-bs-* attributes
        var 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.
        var modalTitle = exampleModal.querySelector('.modal-title')
        var modalBodyInput = exampleModal.querySelector('.modal-body input')

        modalTitle.textContent = '给 ' + recipient + '的新消息'
        modalBodyInput.value = recipient
      })
在模态框之间切换

通过巧妙地放置 data-bs-targetdata-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">
              <h6 class="modal-title" id="exampleModalToggleLabel">模态框 1</h6>
              <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 class="btn btn-primary" data-bs-target="#exampleModalToggle2" data-bs-toggle="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">
              <h6 class="modal-title" id="exampleModalToggleLabel2">模态框 2</h6>
              <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 class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">返回第一个模态框</button>
            </div>
          </div>
        </div>
      </div>
      <a class="btn btn-primary" data-bs-toggle="modal" href="#exampleModalToggle" role="button">打开第一个模态框</a>
更改动画

$modal-fade-transform 变量决定了 .modal-dialog 在模态淡入动画之前的变换状态,$modal-show-transform 变量决定了 .modal-dialog 在模态淡入动画结束时的变换。

例如,如果你想要一个放大动画,你可以设置 $modal-fade-transform: scale(.8)

移除动画

对于只是出现而不是淡入查看的模态,请从模态标记中删除 .fade 类。

<div class="modal" tabindex="-1" aria-labelledby="..." aria-hidden="true">
        ...
      </div>
动态高度

如果模态框在打开时高度发生变化,您应该调用 myModal.handle Update() 来调整模态框的位置,以防出现滚动条。

可访问性

请务必将引用模态标题的 aria-labelledby="..." 添加到 .modal。 此外,您可以在 .modal 上使用 aria- describeby 来描述您的模态对话框。 请注意,您不需要添加 role="dialog",因为我们已经通过 JavaScript 添加了它。

嵌入 YouTube 视频

在模态中嵌入 YouTube 视频需要额外的 JavaScript,而不是 Bootstrap 来自动停止播放等等。 查看这篇有用的 Stack Overflow 帖子了解更多信息。

可选尺寸

模态框有三种可选尺寸,可通过修饰符类放置在 .modal-dialog 上。 这些尺寸在某些断点处开始,以避免在较窄的视口上出现水平滚动条。

尺寸 Class 模态框最大宽度
.modal-sm 300px
默认 None 500px
.modal-lg 800px
特大 .modal-xl 1140px

我们没有修饰符类的默认模态构成了 “medium” 大小模态。

<div class="modal-dialog modal-xl">...</div>
      <div class="modal-dialog modal-lg">...</div>
      <div class="modal-dialog modal-sm">...</div>
全屏模式

另一个覆盖是弹出覆盖用户视口的模式的选项,可通过放置在 .modal-dialog 上的修饰符类获得。

Class 可用性
.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 以下
<!-- 全屏模态框 -->
      <div class="modal-dialog modal-fullscreen-sm-down">
        ...
      </div>
用法

模态插件通过数据属性或 JavaScript 按需切换隐藏内容。 它还覆盖默认滚动行为并生成一个 .modal-backdrop 以提供一个单击区域,以便在单击模态框外时关闭显示的模态框。

通过数据属性
Toggle

无需编写 JavaScript 即可激活模式。 在控制器元素(如按钮)上设置 data-bs-toggle="modal" 以及 data-bs-target="#foo" 或 < code>href="#foo" 以指定要切换的模式。

<button type="button" data-bs-toggle="modal" data-bs-target="#myModal">Launch modal</button>
Dismiss

可以通过 模态 按钮上的 data 属性实现解除,如下所示:

<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>

或使用 data-bs-target模态框外 的按钮上,如下所示:

<button type="button" class="btn-close" data-bs-dismiss="modal" data-bs-target="#my-modal" aria-label="Close"></button>
虽然支持解除模态的两种方式,但请记住,从模态外部解除与 WAI-ARIA 模式对话框设计模式。这样做需要您自担风险。
通过 JavaScript

用一行 JavaScript 创建一个模态框:

var myModal = new bootstrap.Modal(document.getElementById('myModal'), options)
选项

选项可以通过数据属性或 JavaScript 传递。 对于数据属性,将选项名称附加到 data-bs-,如 data-bs-backdrop=""

姓名 类型 默认 描述
backdrop boolean or the string 'static' true 包括一个模态背景元素。 或者,为在单击时不关闭模式的背景指定 static
keyboard boolean true 按下退出键时关闭模态
focus boolean true 初始化时将焦点放在模式上。
方法
异步方法和转换

所有 API 方法都是异步并启动transition。 它们会在过渡开始后但在过渡结束之前返回给调用者。 此外,转换组件上的方法调用将被忽略

传递选项

将您的内容激活为模式。 接受可选选项object

var myModal = new bootstrap.Modal(document.getElementById('myModal'), {
        keyboard: false
      })
toggle

手动切换模式。 在模态框实际显示或隐藏之前返回调用者(即在 shown.bs.modalhidden.bs.modal 事件之前 发生)。

myModal.toggle()
show

手动打开一个模态框。 在模态框实际显示之前返回调用者(即在 shown.bs.modal 事件发生之前)。

myModal.show()

此外,您可以将 DOM 元素作为可在模式事件中接收的参数传递(作为 relatedTarget 属性)。

var modalToggle = document.getElementById('toggleMyModal') // relatedTarget
      myModal.show(modalToggle)
hide

手动隐藏模态框。 在模态框实际隐藏之前返回调用者(即在 hidden.bs.modal 事件发生之前)。

myModal.hide()
handleUpdate

如果模态框在打开时的高度发生变化(即出现滚动条时),请手动重新调整模态框的位置。

myModal.handleUpdate()
dispose

销毁元素的模态。(删除 DOM 元素上存储的数据)

myModal.dispose()
getInstance

Static 方法,允许您获取与 DOM 元素关联的模态实例。

var myModalEl = document.getElementById('myModal')
      var modal = bootstrap.Modal.getInstance(myModalEl) // Returns a Bootstrap modal instance
getOrCreateInstance

Static 方法,该方法允许您获取与 DOM 元素关联的模式实例,或者在未初始化的情况下创建一个新实例。

var myModalEl = document.querySelector('#myModal')
      var modal = bootstrap.Modal.getOrCreateInstance(myModalEl) // Returns a Bootstrap modal instance
事件

Bootstrap 的模态类公开了一些用于连接模态功能的事件。 所有模态事件都在模态本身触发(即在 <div class="modal"> 处)。

事件类型 描述
show.bs.modal 此事件在调用 show 实例方法时立即触发。 如果由单击引起,则单击的元素可用作事件的 relatedTarget 属性。
shown.bs.modal 当模式对用户可见时触发此事件(将等待 CSS 转换完成)。 如果由单击引起,则单击的元素可用作事件的 relatedTarget 属性。
hide.bs.modal 当调用 hide 实例方法时,会立即触发此事件。
hidden.bs.modal 当模态对用户隐藏完成时会触发此事件(将等待 CSS 转换完成)。
hidePrevented.bs.modal 当显示模式时触发此事件,其背景为 static 并且使用键盘选项或 data-bs-keyboard 执行模式外的单击或退出键按下设置为 false
var myModalEl = document.getElementById('myModal')
      myModalEl.addEventListener('hidden.bs.modal', function (event) {
        // do something...
      })