Skip to main content Skip to docs navigation

弹窗

使用 Bootstrap 的 JavaScript 模式插件将对话框添加到你的网站，以显示灯箱、用户通知或完全自定义的内容。

目录

怎么运行的

¥How it works

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

¥Before getting started with Bootstrap’s modal component, be sure to read the following as our menu options have recently changed.

  • 模态框是使用 HTML、CSS 和 JavaScript 构建的。它们位于文档中的其他所有内容之上，并从 <body> 中删除滚动，以便模式内容滚动。

    ¥Modals are built with HTML, CSS, and JavaScript. They’re positioned over everything else in the document and remove scroll from the <body> so that modal content scrolls instead.

  • 单击模态 “backdrop” 将自动关闭模态。

    ¥Clicking on the modal “backdrop” will automatically close the modal.

  • Bootstrap 一次仅支持一个模式窗口。不支持嵌套模式，因为我们认为它们的用户体验很差。

    ¥Bootstrap only supports one modal window at a time. Nested modals aren’t supported as we believe them to be poor user experiences.

  • 模态框使用 position: fixed，有时它的渲染可能有点特殊。只要有可能，请将模态 HTML 放置在顶层位置，以避免其他元素的潜在干扰。将 .modal 嵌套在另一个固定元素中时，你可能会遇到问题。

    ¥Modals use position: fixed, which can sometimes be a bit particular about its rendering. Whenever possible, place your modal HTML in a top-level position to avoid potential interference from other elements. You’ll likely run into issues when nesting a .modal within another fixed element.

  • 再次，由于 position: fixed，在移动设备上使用模态有一些注意事项。See our browser support docs for details.

    ¥Once again, due to position: fixed, there are some caveats with using modals on mobile devices. See our browser support docs for details.

  • 由于 HTML5 定义其语义的方式，autofocus HTML 属性 在 Bootstrap 模式中没有效果。要达到相同的效果，请使用一些自定义 JavaScript：

    ¥Due to how HTML5 defines its semantics, the autofocus HTML attribute has no effect in Bootstrap modals. To achieve the same effect, use some custom JavaScript:

const myModal = document.getElementById('myModal')
const myInput = document.getElementById('myInput')

myModal.addEventListener('shown.bs.modal', () => {
  myInput.focus()
})
The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation.

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

¥Keep reading for demos and usage guidelines.

示例

¥Examples

¥Modal components

下面是一个静态模态示例（意味着它的 position 和 display 已被覆盖）。包括模态页眉、模态正文（padding 必需）和模态页脚（可选）。我们要求你尽可能在关闭操作中包含模态标题，或者提供另一个显式关闭操作。

¥Below is a static modal example (meaning its position and display have been overridden). Included are the modal header, modal body (required for padding), and modal footer (optional). We ask that you include modal headers with dismiss actions whenever possible, or provide another explicit dismiss action.

模态标题

模态正文文本位于此处。

¥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>
In the above static example, we use <h5>, to avoid issues with the heading hierarchy in the documentation page. Structurally, however, a modal dialog represents its own separate document/context, so the .modal-title should ideally be an <h1>. If necessary, you can use the font size utilities to control the heading’s appearance. All the following live examples use this approach.

在线演示

¥Live demo

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

¥Toggle a working modal demo by clicking the button below. It will slide down and fade in from the top of the page.

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

静态背景

¥Static backdrop

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

¥When backdrop is set to static, the modal will not close when clicking outside of it. Click the button below to try it.

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

滚动长内容

¥Scrolling long content

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

¥When modals become too long for the user’s viewport or device, they scroll independent of the page itself. Try the demo below to see what we mean.

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

¥You can also create a scrollable modal that allows scrolling the modal body by adding .modal-dialog-scrollable to .modal-dialog.

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

垂直居中

¥Vertically centered

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

¥Add .modal-dialog-centered to .modal-dialog to vertically center the modal.

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

工具提示和弹出窗口

¥Tooltips and popovers

Tooltips and popovers can be placed within modals as needed.当模式关闭时，其中的任何工具提示和弹出窗口也会自动消失。

¥Tooltips and popovers can be placed within modals as needed. When modals are closed, any tooltips and popovers within are also automatically dismissed.

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

使用网格

¥Using the grid

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

¥Utilize the Bootstrap grid system within a modal by nesting .container-fluid within the .modal-body. Then, use the normal grid system classes as you would anywhere else.

<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-* 属性 根据单击的按钮改变模式的内容。

¥Have a bunch of buttons that all trigger the same modal with slightly different contents? Use event.relatedTarget and HTML data-bs-* attributes to vary the contents of the modal depending on which button was clicked.

下面是一个在线演示，后面是 HTML 和 JavaScript 示例。如需了解更多信息，请联系 阅读模态事件文档 了解有关 relatedTarget 的详细信息。

¥Below is a live demo followed by example HTML and JavaScript. For more information, read the modal events docs for details on relatedTarget.

html 
<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>
site/assets/js/partials/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
  })
}

在模态之间切换

¥Toggle between modals

通过巧妙放置 data-bs-target 和 data-bs-toggle 属性，在多个模式之间切换。例如，你可以从已打开的登录模式中切换密码重置模式。请注意，多个模式不能同时打开 - 此方法只是在两个单独的模式之间切换。

¥Toggle between multiple modals with some clever placement of the data-bs-target and data-bs-toggle attributes. For example, you could toggle a password reset modal from within an already open sign in modal. Please note multiple modals cannot be open at the same time—this method simply toggles between two separate modals.

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

改变动画

¥Change animation

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

¥The $modal-fade-transform variable determines the transform state of .modal-dialog before the modal fade-in animation, the $modal-show-transform variable determines the transform of .modal-dialog at the end of the modal fade-in animation.

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

¥If you want for example a zoom-in animation, you can set $modal-fade-transform: scale(.8).

删除动画

¥Remove animation

对于仅显示而不是淡入视图的模态框，请从模态标记中删除 .fade 类。

¥For modals that simply appear rather than fade in to view, remove the .fade class from your modal markup.

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

动态高度

¥Dynamic heights

如果模态框的高度在打开时发生变化，则应调用 myModal.handleUpdate() 重新调整模态框的位置，以防出现滚动条。

¥If the height of a modal changes while it is open, you should call myModal.handleUpdate() to readjust the modal’s position in case a scrollbar appears.

无障碍

¥Accessibility

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

¥Be sure to add aria-labelledby="...", referencing the modal title, to .modal. Additionally, you may give a description of your modal dialog with aria-describedby on .modal. Note that you don’t need to add role="dialog" since we already add it via JavaScript.

嵌入 YouTube 视频

¥Embedding YouTube videos

在模态中嵌入 YouTube 视频需要 Bootstrap 中没有的额外 JavaScript 来自动停止播放等。请参阅这篇有用的 Stack Overflow 帖子 了解更多信息。

¥Embedding YouTube videos in modals requires additional JavaScript not in Bootstrap to automatically stop playback and more. See this helpful Stack Overflow post for more information.

可选尺寸

¥Optional sizes

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

¥Modals have three optional sizes, available via modifier classes to be placed on a .modal-dialog. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.

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

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

¥Our default modal without modifier class constitutes the “medium” size modal.

<div class="modal-dialog modal-xl">...</div>
<div class="modal-dialog modal-lg">...</div>
<div class="modal-dialog modal-sm">...</div>

全屏模态

¥Fullscreen Modal

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

¥Another override is the option to pop up a modal that covers the user viewport, available via modifier classes that are placed on a .modal-dialog.

Class Availability
.modal-fullscreen Always
.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>

CSS

变量

¥Variables

Added in v5.2.0

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，模态现在在 .modal 和 .modal-backdrop 上使用本地 CSS 变量来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。

¥As part of Bootstrap’s evolving CSS variables approach, modals now use local CSS variables on .modal and .modal-backdrop for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

scss/_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}; // Todo in v6: Split this padding into x and y
--#{$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};
scss/_modal.scss 
--#{$prefix}backdrop-zindex: #{$zindex-modal-backdrop};
--#{$prefix}backdrop-bg: #{$modal-backdrop-bg};
--#{$prefix}backdrop-opacity: #{$modal-backdrop-opacity};

Sass 变量

¥Sass variables

scss/_variables.scss 
$modal-inner-padding:               $spacer;

$modal-footer-margin-between:       .5rem;

$modal-dialog-margin:               .5rem;
$modal-dialog-margin-y-sm-up:       1.75rem;

$modal-title-line-height:           $line-height-base;

$modal-content-color:               null;
$modal-content-bg:                  var(--#{$prefix}body-bg);
$modal-content-border-color:        var(--#{$prefix}border-color-translucent);
$modal-content-border-width:        var(--#{$prefix}border-width);
$modal-content-border-radius:       var(--#{$prefix}border-radius-lg);
$modal-content-inner-border-radius: subtract($modal-content-border-radius, $modal-content-border-width);
$modal-content-box-shadow-xs:       var(--#{$prefix}box-shadow-sm);
$modal-content-box-shadow-sm-up:    var(--#{$prefix}box-shadow);

$modal-backdrop-bg:                 $black;
$modal-backdrop-opacity:            .5;

$modal-header-border-color:         var(--#{$prefix}border-color);
$modal-header-border-width:         $modal-content-border-width;
$modal-header-padding-y:            $modal-inner-padding;
$modal-header-padding-x:            $modal-inner-padding;
$modal-header-padding:              $modal-header-padding-y $modal-header-padding-x; // Keep this for backwards compatibility

$modal-footer-bg:                   null;
$modal-footer-border-color:         $modal-header-border-color;
$modal-footer-border-width:         $modal-header-border-width;

$modal-sm:                          300px;
$modal-md:                          500px;
$modal-lg:                          800px;
$modal-xl:                          1140px;

$modal-fade-transform:              translate(0, -50px);
$modal-show-transform:              none;
$modal-transition:                  transform .3s ease-out;
$modal-scale-transform:             scale(1.02);

Sass 循环

¥Sass loops

响应式全屏模式 是通过 $breakpoints 映射和 scss/_modal.scss 中的循环生成的。

¥Responsive fullscreen modals are generated via the $breakpoints map and a loop in scss/_modal.scss.

scss/_modal.scss 
@each $breakpoint in map-keys($grid-breakpoints) {
  $infix: breakpoint-infix($breakpoint, $grid-breakpoints);
  $postfix: if($infix != "", $infix + "-down", "");

  @include media-breakpoint-down($breakpoint) {
    .modal-fullscreen#{$postfix} {
      width: 100vw;
      max-width: none;
      height: 100%;
      margin: 0;

      .modal-content {
        height: 100%;
        border: 0;
        @include border-radius(0);
      }

      .modal-header,
      .modal-footer {
        @include border-radius(0);
      }

      .modal-body {
        overflow-y: auto;
      }
    }
  }
}

用法

¥Usage

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

¥The modal plugin toggles your hidden content on demand, via data attributes or JavaScript. It also overrides default scrolling behavior and generates a .modal-backdrop to provide a click area for dismissing shown modals when clicking outside the modal.

通过数据属性

¥Via data attributes

切换

¥Toggle

无需编写 JavaScript 即可激活模式。在控制器元素（如按钮）上设置 data-bs-toggle="modal" 以及 data-bs-target="#foo" 或 href="#foo" 以针对要切换的特定模式。

¥Activate a modal without writing JavaScript. Set data-bs-toggle="modal" on a controller element, like a button, along with a data-bs-target="#foo" or href="#foo" to target a specific modal to toggle.

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

退出

¥Dismiss

Dismissal can be achieved with the data-bs-dismiss attribute on a button within the modal as demonstrated below:

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

or on a button outside the modal using the additional data-bs-target as demonstrated below:

<button type="button" class="btn-close" data-bs-dismiss="modal" data-bs-target="#my-modal" aria-label="Close"></button>
While both ways to dismiss a modal are supported, keep in mind that dismissing from outside a modal does not match the ARIA Authoring Practices Guide dialog (modal) pattern. Do this at your own risk.

通过 JavaScript

¥Via JavaScript

使用一行 JavaScript 创建一个模式：

¥Create a modal with a single line of JavaScript:

const myModal = new bootstrap.Modal(document.getElementById('myModal'), options)
// or
const myModalAlternative = new bootstrap.Modal('#myModal', options)

选项

¥Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

Name Type Default Description
backdrop boolean, 'static' true Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn’t close the modal when clicked.
focus boolean true Puts the focus on the modal when initialized.
keyboard boolean true Closes the modal when escape key is pressed.

方法

¥Methods

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started, but before it ends. In addition, a method call on a transitioning component will be ignored. Learn more in our JavaScript docs.

传递选项

¥Passing options

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

¥Activates your content as a modal. Accepts an optional options object.

const myModal = new bootstrap.Modal('#myModal', {
  keyboard: false
})
Method Description
dispose Destroys an element’s modal. (Removes stored data on the DOM element)
getInstance Static method which allows you to get the modal instance associated with a DOM element.
getOrCreateInstance Static method which allows you to get the modal instance associated with a DOM element, or create a new one in case it wasn’t initialized.
handleUpdate Manually readjust the modal’s position if the height of a modal changes while it is open (i.e. in case a scrollbar appears).
hide Manually hides a modal. Returns to the caller before the modal has actually been hidden (i.e. before the hidden.bs.modal event occurs).
show Manually opens a modal. Returns to the caller before the modal has actually been shown (i.e. before the shown.bs.modal event occurs). Also, you can pass a DOM element as an argument that can be received in the modal events (as the relatedTarget property). (i.e. const modalToggle = document.getElementById('toggleMyModal'); myModal.show(modalToggle).
toggle Manually toggles a modal. Returns to the caller before the modal has actually been shown or hidden (i.e. before the shown.bs.modal or hidden.bs.modal event occurs).

活动

¥Events

Bootstrap 的模态类公开了一些用于钩子模态功能的事件。所有模态事件均在模态本身（即 <div class="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 Description
hide.bs.modal This event is fired immediately when the hide instance method has been called.
hidden.bs.modal This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).
hidePrevented.bs.modal This event is fired when the modal is shown, its backdrop is static and a click outside of the modal is performed. The event is also fired when the escape key is pressed and the keyboard option is set to false.
show.bs.modal This event fires immediately when the show instance method is called. If caused by a click, the clicked element is available as the relatedTarget property of the event.
shown.bs.modal This event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete). If caused by a click, the clicked element is available as the relatedTarget property of the event. 
const myModalEl = document.getElementById('myModal')
myModalEl.addEventListener('hidden.bs.modal', event => {
  // do something...
})