使用 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 模态示例(意味着它的 position
和 display
已被覆盖)。 包括模态标题、模态正文(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.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">打开模态 @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-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"> <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>
通过 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.modal
或 hidden.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 instancegetOrCreateInstance
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... })