跳到主题内容 跳到文档导航栏

模态框

使用Bootstrap的JavaScript模式插件将对话框添加到站点中，用于lightbox、用户通知或完全自定义的内容。

在本页面

怎样工作

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

  • Modals是用HTML、CSS和JavaScript构建的。它们位于文档中其他所有内容之上，并从<body>中删除scroll，这样模态内容就会滚动。
  • 点击模态“backdrop”将自动关闭模态。
  • Bootstrap一次只支持一个模式窗口。嵌套modals不受支持，因为我们认为它们是糟糕的用户体验。
  • Modals 使用 position: fixed，这有时对其渲染有点特殊。尽可能将模态HTML放在顶层位置，以避免来自其他元素的潜在干扰。在另一个固定元素中嵌套.modal时，可能会遇到问题。
  • 同样，由于position: fixed的原因，在移动设备上使用 modals有一些注意事项。有关详细信息，请参阅我们的浏览器支持文档。
  • 由于HTML5如何定义其语义， autofocus HTML属性在Bootstrap modals中不起作用。要达到相同的效果，请使用一些自定义JavaScript：
var myModal = document.getElementById('myModal')
var myInput = document.getElementById('myInput')

myModal.addEventListener('shown.bs.modal', function () {
  myInput.focus()
})
此组件的动画效果取决于prefers-reduced-motion媒体查询。 请参阅 我们的可访问性文档的简化运动部分。

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

示例

下面是一个 静态 模态示例（表示其position和display已被覆盖）。包括模态页眉、模态正文（ padding时需要）和模态页脚（可选）。 我们要求您尽可能将模态头包含在dismise操作中，或者提供另一个显式dismise操作。

Modal title

Modal body text goes here.

<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>

现场演示

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

<!-- 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">
        <h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
        <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>

静态背景

When backdrop is set to static, the modal will not close when clicking outside it. Click the button below to try it. 当背景设置为static时，当在其外部单击时，模式将不会关闭。单击下面的按钮进行尝试。

<!-- 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">
        <h5 class="modal-title" id="staticBackdropLabel">Modal title</h5>
        <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>

滚动长内容

当模态对于用户的视口或设备来说太长时，它们会独立于页面本身滚动。尝试下面的演示，看看我们的意思。

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

<!-- Scrollable modal -->
<div class="modal-dialog modal-dialog-scrollable">
  ...
</div>

垂直居中

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

<!-- 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>

工具提示和弹出窗口

工具提示 和 弹出窗口可以根据需要放置在modals中。当modals关闭时，其中的任何工具提示和弹出窗口也会自动关闭。

<div class="modal-body">
  <h5>Popover in a modal</h5>
  <p>This <a href="#" role="button" class="btn btn-secondary popover-test" title="Popover title" data-bs-content="Popover body content is set in this attribute.">button</a> triggers a popover on click.</p>
  <hr>
  <h5>Tooltips in a modal</h5>
  <p><a href="#" class="tooltip-test" title="Tooltip">This link</a> and <a href="#" class="tooltip-test" title="Tooltip">that link</a> have tooltips on hover.</p>
</div>

使用网格

通过在.modal-body 中嵌套 .container-fluid，利用modal中的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>

各种模态内容

有一堆按钮都触发相同的模式，但内容略有不同吗？使用event.relatedTarget和HTML data-bs-* 属性 ，以根据单击的按钮改变模态的内容。

下面是一个实时演示，后面是示例HTML和JavaScript。有关更多信息，请阅读 模态事件文档以了解relatedTarget的详细信息。

<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">
        <h5 class="modal-title" id="exampleModalLabel">New message</h5>
        <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>
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 = 'New message to ' + recipient
  modalBodyInput.value = recipient
})

变更动画

$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.handleUpdate()在出现滚动条时重新调整模态的位置。

辅助功能

确保将Bootstrap模态标题的aria-labelledby="..."添加到.modal。此外，您还可以使用.modal上的 aria-describedby来描述模态对话框。注意，您不需要添加role="dialog"，因为我们已经通过JavaScript添加了它。

嵌入YouTube视频

在modals中嵌入YouTube视频需要额外的JavaScript（不在 Bootstrap中）来自动停止播放等等。有关更多信息，请参阅这篇有用的堆栈溢出文章.

可选尺寸

模态有三个可选的大小，可以通过放置在.modal-dialog的修饰符类获得。这些大小在某些断点处生效，以避免在较窄的视口中出现水平滚动条。

大小 类 模态 max-width
Small .modal-sm 300px
Default None 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>

全屏模式

另一个替代选项是弹出一个覆盖用户视口的模式，可以通过放置在.modal-dialog上的修改器类获得。

类 可用
.modal-fullscreen Always
.modal-fullscreen-sm-down Below 576px
.modal-fullscreen-md-down Below 768px
.modal-fullscreen-lg-down Below 992px
.modal-fullscreen-xl-down Below 1200px
.modal-fullscreen-xxl-down Below 1400px 
<!-- Full screen modal -->
<div class="modal-dialog modal-fullscreen-sm-down">
  ...
</div>

用法

模态插件通过数据属性或JavaScript按需切换隐藏内容。它还将 .modal-open 添加到e <body> 以覆盖默认的滚动行为，并生成一个 .modal-backdrop 以提供一个单击区域，以便在模态外单击时忽略显示的模态。

通过数据属性

在不编写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>

通过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 按escape键时关闭模式
focus boolean true 初始化时将焦点放在模态上。

方法

异步方法和转换

所有API方法都是异步的，并开始转换。转换一开始就返回到调用方，但在转换结束之前返回。 此外，对 转换组件的方法调用将被忽略。

有关更多信息，请参阅我们的JavaScript文档。

传递选项

将内容激活为模态。接受可选选项 object.

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

toggle

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

myModal.toggle()

show

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

myModal.show()

hide

手动隐藏模式。在模态实际被隐藏之前返回调用者 （即在 hidden.bs.modal 事件发生）。

myModal.hide()

handleUpdate

如果模态打开时高度发生变化（即出现滚动条），则手动重新调整模态的位置。

myModal.handleUpdate()

dispose

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

myModal.dispose()

getInstance

静态方法，该方法允许您获取与DOM元素关联的模态实例。

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

事件

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

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