弹出模态框 (Modal)

使用Bootstrap的JavaScript模态框插件可以为您的网站添加醒目的提示和交互,用于通知用户、访客交互、消息警示或自定义的内容交互(如考试问答场景-译者注)

运行原理

在开始使用Bootstrap模态框组件前,请务必阅读以下内容,因为我们的菜单选项最近有新的更改迭代。

  • 弹出模态框是用HTML、CSS和Javascript构建的,它们位于文档中其它表现元素之上,并从<body>中删除滚动事件,以便模态框自身的内容能得到滚动。
  • 点击模态框的“backdrop”(灰背景区域),将自动关闭动态模块框。
  • Bootstrap一次只支持一个模态窗口,不支持嵌套模式,因为我们相信那样叠加会造成用户体验不佳。
  • 模态框使用 position: fixed,在呈现上与其它元素相比有很大不同。请尽可能将弹出模态框的HTML放在顶级位置,以避免其它元素干扰,尤其是当另一个固定元素中也定义了 .modal 事件时,你可能会遇到问题。
  • 同样是受position: fixed属性影响,在在移动设备上使用模态框,有一些注意事项。有关详细信息,请参阅浏览器支持文档。
  • 根据HTML5的语义定义, autofocus HTML 属性对 Bootstrap 模态框没有影响,要达到同样的效果,需要使用一些JavaScript:
$('#myModal').on('shown.bs.modal', function () {
  $('#myInput').trigger('focus')
})

此组件的动画效果取决于prefers-reduced-motion 媒体查询. 请参阅我们的 辅助功能文档的简化动作部分。.

继续查看范例和文档:

示例

下面是一个静态 模式的例子(其 positiondisplay 已经被重写 ),包括模态标题、模态体 (需要 padding)、模态页脚(可选),我们要求你尽可能地在模态标题区加上移除关闭按钮,或提供另一个明确的关闭动作。

<div class="modal" tabindex="-1" role="dialog">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title">Modal title</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        <p>Modal body text goes here.</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-primary">Save changes</button>
        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
      </div>
    </div>
  </div>
</div>

完整示例

点击下面按钮,能呼出动态窗口,即切换到模态框的动态模式,它将从页面顶部向下浮动并淡入展现:

<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

滚动长内容

当用户viewport 视口(弹出内容区)或设备的模态变得较长时,它们会自动滚动页面,点击下面的演示可以看到:

<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalLong">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal fade" id="exampleModalLong" tabindex="-1" role="dialog" aria-labelledby="exampleModalLongTitle" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLongTitle">Modal title</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

居中显示

.modal-dialog-centered 添加到 .modal-dialog 对话框以垂直居中模式。

<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalCenter">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal fade" id="exampleModalCenter" tabindex="-1" role="dialog" aria-labelledby="exampleModalCenterTitle" aria-hidden="true">
  <div class="modal-dialog modal-dialog-centered" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalCenterTitle">Modal title</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Tooltips工具提示和弹出提示框

Tooltips工具提示popovers 提示框,可以根据需要放置在模态框中。当模态框关闭时,其包含的任何提示和Pop提示都会同步关闭。

<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-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 栅格系统,可以在动态视窗中使用Bootsrap栅格系统,并在任何地方使用正常的栅格系统class定义。

<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 ml-auto">.col-md-4 .ml-auto</div>
    </div>
    <div class="row">
      <div class="col-md-3 ml-auto">.col-md-3 .ml-auto</div>
      <div class="col-md-2 ml-auto">.col-md-2 .ml-auto</div>
    </div>
    <div class="row">
      <div class="col-md-6 ml-auto">.col-md-6 .ml-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-* 属性 (或通过 使用 jQuery)依据所点按钮的定义来动态加载弹出窗口中的内容。

下面即是一组基于HTML和 JavaScript组合使用的范例,更多细节可参考 模态框事件 中的 relatedTarget属性。

<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@mdo">Open modal for @mdo</button>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@fat">Open modal for @fat</button>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@getbootstrap">Open modal for @getbootstrap</button>

<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">New message</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        <form>
          <div class="form-group">
            <label for="recipient-name" class="col-form-label">Recipient:</label>
            <input type="text" class="form-control" id="recipient-name">
          </div>
          <div class="form-group">
            <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-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Send message</button>
      </div>
    </div>
  </div>
</div>
$('#exampleModal').on('show.bs.modal', function (event) {
  var button = $(event.relatedTarget) // Button that triggered the modal
  var recipient = button.data('whatever') // Extract info from data-* attributes
  // If necessary, you could initiate an AJAX request here (and then do the updating in a callback).
  // Update the modal's content. We'll use jQuery here, but you could use a data binding library or other methods instead.
  var modal = $(this)
  modal.find('.modal-title').text('New message to ' + recipient)
  modal.find('.modal-body input').val(recipient)
})

移除动画效果

如果只要弹出模态而不需要淡入淡出效果,请从你的模态窗元素中定义移除 .fade 即可(aria-hidden="true"

<div class="modal" tabindex="-1" role="dialog" aria-labelledby="..." aria-hidden="true">
  ...
</div>

动态高度

如果模态的高度在打开时发生变化,则应调用code class="highlighter-rouge">$('#myModal').data('bs.modal').handleUpdate() 或 $('#myModal').modal('handleUpdate') 重新调整模态框的位置,以防滚动条出现。

无障碍易用性处理

请务必在.modalrole="document"模态框标题的.modal-dialog 中添加 .modal-dialogaria-labelledby="..."。另外,您可以使用 .modal 上的 aria-descriptby 來描述你的動態視窗,优化无障碍浏览。

嵌入 YouTube 视频

嵌入YouTube视频的模式需要额外的JavaScript,同时Bootstrap不能提供自动停止播放和更多控制。有关更多信息,请参阅Stack Overflow 上的这篇文章

尺寸大小选项

模态框有两个可选大小,可以通过class定义.modal-dialog(分别是.bd-example-modal-lg.bd-example-modal-sm,这些尺寸会在某些中断点调整,以避免在较小的viewport窗口上出现水平滚动条。

Size Class Modal max-width
Small .modal-sm 300px
Default None 500px
Large .modal-lg 800px
Extra large .modal-xl 1140px

我们的默认模态没有修饰符类构成“中”大小模态.

<!-- Extra large modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-xl">Extra large modal</button>

<div class="modal fade bd-example-modal-xl" tabindex="-1" role="dialog" aria-labelledby="myExtraLargeModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-xl">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

<!-- Large modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-lg">Large modal</button>

<div class="modal fade bd-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-lg">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

<!-- Small modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-sm">Small modal</button>

<div class="modal fade bd-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-sm">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

用法

模态插件通过数据属性或JavaScript按需切换您隐藏的内容。它将.modal-open加到了<body>上,以覆盖默认的滚动行为,并生成.modal-backdrop来提供点击区域,以便在动态模态窗外面点击一下就能移除模态。

使用数据属性

启动一个动态视窗而无需编写JavaScript,在控制元素上设置data-toggle="modal"(如按钮),以及一个data-target="#foo"href="#foo" 来指定特定的动态视窗进行切换。

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

通过JavaScript

使用单行JavaScript调用ID为 myModal的动态模态框:

$('#myModal').modal(options)

选项

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

名称 Type类型 默认值 描述
backdrop boolean or the string 'static' true 包括动态视窗背景元素,或者指定 static在点击背景时不关闭动态模态框。
keyboard boolean true 按下esc时关闭动态视窗。
focus boolean true 初始化focus动态视窗。
show boolean true 初始化时显示模态。

方法

异步传输与转换

所有的API方法都支持异步传输,且一旦 转换开始,在结束之前它们会返回给调用者,直到完成这个动画。另外, 过渡组件上的方法将被忽略。

请参阅JavaScript文档以了解更多信息。

.modal(options)

激活您的内容作为模态,将选项加入到 object内。

$('#myModal').modal({
  keyboard: false
})

.modal('toggle')

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

$('#myModal').modal('toggle')

.modal('show')

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

$('#myModal').modal('show')

.modal('hide')

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

$('#myModal').modal('hide')

.modal('handleUpdate')

如果动态模态框在打开状态(比如在出现滚动条的情况下)重新改变高度,并调整模态窗的位置。

$('#myModal').modal('handleUpdate')

.modal('dispose')

销毁一个元素的Modal。

事件

Bootstrap’s modal class exposes a few events for hooking into modal functionality. All modal events are fired at the modal itself (i.e. at the <div class="modal">).

Event事件类型 描述
show.bs.modal 当调用show实例方法时,会立即触发该事件。如果是由点击引起的,被点击的元素是可用的,成为Event对象的relatedTarget属性。
shown.bs.modal 当模态框对用户来说可见时(需要等待CSS过渡完成),会触发该事件。如果是由点击引起的,被点击的元素是可用的,成为Event对象的relatedTarget属性。
hide.bs.modal 当调用hide实例方法时,会立即触发该事件。
hidden.bs.modal 当模态框对用户来说终于完成隐藏时(需要等待CSS过渡完成),会触发该事件。
$('#myModal').on('hidden.bs.modal', function (e) {
  // do something...
})