Skip to main content Skip to docs navigation
View on GitHub

警告框（Alert）

通过精炼且适当的警告消息为典型的用户操作提供契合上下文的反馈。

On this page

示例

警告框（alert）组件能够展示任意长度的文本以及一个可选的关闭按钮。为了展示合适的样式，必须 从下列 8 个情境类（例如 .alert-success）中选择一个合适的并使用。如需内联一个关闭按钮，请使用 警告框（alert）的 JavaScript 插件。

Heads up! As of v5.3.0, the alert-variant() Sass mixin is deprecated. Alert variants now have their CSS variables overridden in the Sass loop.
html 
<div class="alert alert-primary" role="alert">
  A simple primary alert—check it out!
</div>
<div class="alert alert-secondary" role="alert">
  A simple secondary alert—check it out!
</div>
<div class="alert alert-success" role="alert">
  A simple success alert—check it out!
</div>
<div class="alert alert-danger" role="alert">
  A simple danger alert—check it out!
</div>
<div class="alert alert-warning" role="alert">
  A simple warning alert—check it out!
</div>
<div class="alert alert-info" role="alert">
  A simple info alert—check it out!
</div>
<div class="alert alert-light" role="alert">
  A simple light alert—check it out!
</div>
<div class="alert alert-dark" role="alert">
  A simple dark alert—check it out!
</div>
Conveying meaning to assistive technologies

Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (e.g. the visible text), or is included through alternative means, such as additional text hidden with the .visually-hidden class.

实例

点击下面的按钮触发警告框（alert）（初始是隐藏的，添加了内联样式），然后点击关闭按钮将其关闭（并销毁）。

html 
<div id="liveAlertPlaceholder"></div>
<button type="button" class="btn btn-primary" id="liveAlertBtn">显示警告框（alert）</button>

我们通过以下 JavaScript 代码来触发警告框：

const alertPlaceholder = document.getElementById('liveAlertPlaceholder')

const alert = (message, type) => {
  const wrapper = document.createElement('div')
  wrapper.innerHTML = [
    `<div class="alert alert-${type} alert-dismissible" role="alert">`,
    `   <div>${message}</div>`,
    '   <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>',
    '</div>'
  ].join('')

  alertPlaceholder.append(wrapper)
}

const alertTrigger = document.getElementById('liveAlertBtn')
if (alertTrigger) {
  alertTrigger.addEventListener('click', () => {
    alert('Nice, you triggered this alert message!', 'success')
  })
}

链接的颜色

通过使用 .alert-link 工具类可以为任何警告框（alert）组件添加颜色相匹配的链接。

html 
<div class="alert alert-primary" role="alert">
  A simple primary alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-secondary" role="alert">
  A simple secondary alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-success" role="alert">
  A simple success alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-danger" role="alert">
  A simple danger alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-warning" role="alert">
  A simple warning alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-info" role="alert">
  A simple info alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-light" role="alert">
  A simple light alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-dark" role="alert">
  A simple dark alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>

添加其它内容

警告框（alert）组件还可以包含其它 HTML 元素，例如标题、段落、分割线等。

html 
<div class="alert alert-success" role="alert">
  <h4 class="alert-heading">Well done!</h4>
  <p>Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.</p>
  <hr>
  <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p>
</div>

图标

类似地，你可以使用 flexbox 工具类 以及 Bootstrap 图标集 来创建带有图标的警告框（alert）。针对你所选的图标和内容，你需要为其设置更多的工具类或自定义样式。

html 
<div class="alert alert-primary d-flex align-items-center" role="alert">
  <svg xmlns="http://www.w3.org/2000/svg" class="bi bi-exclamation-triangle-fill flex-shrink-0 me-2" viewBox="0 0 16 16" role="img" aria-label="Warning:">
    <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5zm.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2z"/>
  </svg>
  <div>
    一个带有图标的警告框（alert）示例
  </div>
</div>

需要为警告框（alert）设置多个图标吗？你可以考虑使用更多的 Bootstrap 图标集中的图标，并制作一个本地版本的 SVG sprite，这样可以方便重复地引用相同的图标。

html 
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
  <symbol id="check-circle-fill" viewBox="0 0 16 16">
    <path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zm-3.97-3.03a.75.75 0 0 0-1.08.022L7.477 9.417 5.384 7.323a.75.75 0 0 0-1.06 1.06L6.97 11.03a.75.75 0 0 0 1.079-.02l3.992-4.99a.75.75 0 0 0-.01-1.05z"/>
  </symbol>
  <symbol id="info-fill" viewBox="0 0 16 16">
    <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"/>
  </symbol>
  <symbol id="exclamation-triangle-fill" viewBox="0 0 16 16">
    <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5zm.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2z"/>
  </symbol>
</svg>

<div class="alert alert-primary d-flex align-items-center" role="alert">
  <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Info:"><use xlink:href="#info-fill"/></svg>
  <div>
    一个带有图标的警告框（alert）示例
  </div>
</div>
<div class="alert alert-success d-flex align-items-center" role="alert">
  <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Success:"><use xlink:href="#check-circle-fill"/></svg>
  <div>
    一个带有图标的、表示成功的警告框（alert）示例
  </div>
</div>
<div class="alert alert-warning d-flex align-items-center" role="alert">
  <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Warning:"><use xlink:href="#exclamation-triangle-fill"/></svg>
  <div>
    一个带有图标的、表示警告的警告框（alert）示例
  </div>
</div>
<div class="alert alert-danger d-flex align-items-center" role="alert">
  <svg class="bi flex-shrink-0 me-2" role="img" aria-label="Danger:"><use xlink:href="#exclamation-triangle-fill"/></svg>
  <div>
    A一个带有图标的、表示危险的警告框（alert）示例
  </div>
</div>

关闭警告框

通过使用警告框（alert）组件的 JavaScript 插件，可以为任何警告框（alert）组件添加内联的关闭按钮。步骤如下：

  • 确保已加载了警告框（alert）组件的 JavaScript 插件，或者是 Bootstrap 的预编译 JavaScript 文件。
  • 添加 关闭按钮 和 .alert-dismissible 类，这将在警告框（alert）组件的右侧增加额外的空间并放置关闭按钮。
  • 在关闭按钮上添加 data-bs-dismiss="alert" 属性，该属性会触发 JavaScript 代码。请务必使用 <button> 元素，以确保在所有设备上都具有正确的行为。
  • 如需在关闭警告框（alert）时展示动画效果，请确保添加 .fade 和 .show。

以下是演示效果：

html 
<div class="alert alert-warning alert-dismissible fade show" role="alert">
  <strong>Holy guacamole!</strong> You should check in on some of those fields below.
  <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
</div>
当警告框（alert）被关闭后，该元素将从页面结构中被删除。如果使用键盘的用户通过关闭按钮关闭了警告框（alert），那么将在页面上丢失焦点并被重置为页面/文档的起始位置（该行为取决于浏览器）。出于这个原因，我们建议你添加额外的 JavaScript 代码来监听 closed.bs.alert 事件，并通过代码调用 focus() 将焦点设置为页面中最合适的位置。如果你打算将焦点移到通常不会获取焦点的元素上的话，请确保为该元素添加了 tabindex="-1" 属性。

CSS

变量

Added in v5.2.0

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

  --#{$prefix}alert-bg: transparent;
  --#{$prefix}alert-padding-x: #{$alert-padding-x};
  --#{$prefix}alert-padding-y: #{$alert-padding-y};
  --#{$prefix}alert-margin-bottom: #{$alert-margin-bottom};
  --#{$prefix}alert-color: inherit;
  --#{$prefix}alert-border-color: transparent;
  --#{$prefix}alert-border: #{$alert-border-width} solid var(--#{$prefix}alert-border-color);
  --#{$prefix}alert-border-radius: #{$alert-border-radius};
  --#{$prefix}alert-link-color: inherit;

Sass 变量 

$alert-padding-y:               $spacer;
$alert-padding-x:               $spacer;
$alert-margin-bottom:           1rem;
$alert-border-radius:           $border-radius;
$alert-link-font-weight:        $font-weight-bold;
$alert-border-width:            var(--#{$prefix}border-width);
$alert-bg-scale:                -80%;
$alert-border-scale:            -70%;
$alert-color-scale:             40%;
$alert-dismissible-padding-r:   $alert-padding-x * 3; // 3x covers width of x plus default padding on either side

Sass mixin

Deprecated in v5.3.0

Used in combination with $theme-colors to create contextual modifier classes for our alerts.

@mixin alert-variant($background, $border, $color) {
  --#{$prefix}alert-color: #{$color};
  --#{$prefix}alert-bg: #{$background};
  --#{$prefix}alert-border-color: #{$border};
  --#{$prefix}alert-link-color: #{shade-color($color, 20%)};

  @if $enable-gradients {
    background-image: var(--#{$prefix}gradient);
  }

  .alert-link {
    color: var(--#{$prefix}alert-link-color);
  }
}

Sass loop

Loop that generates the modifier classes with the alert-variant() mixin.

// Generate contextual modifier classes for colorizing the alert
@each $state in map-keys($theme-colors) {
  .alert-#{$state} {
    --#{$prefix}alert-color: var(--#{$prefix}#{$state}-text);
    --#{$prefix}alert-bg: var(--#{$prefix}#{$state}-bg-subtle);
    --#{$prefix}alert-border-color: var(--#{$prefix}#{$state}-border-subtle);
    --#{$prefix}alert-link-color: var(--#{$prefix}#{$state}-text);
  }
}

JavaScript 行为

初始化

将 DOM 元素初始化为警告框（alert）

const alertList = document.querySelectorAll('.alert')
const alerts = [...alertList].map(element => new bootstrap.Alert(element))

如果警告框（alert）的唯一目的就是被关闭的话，就没有必要调用 JS API 手动初始化该组件了。通过设置 data-bs-dismiss="alert"，该组件将自动初始化并正确地关闭。

有关更多详细信息，请参阅 触发器 章节。

触发器

Dismissal can be achieved with the data attribute on a button within the alert as demonstrated below:

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

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

<button type="button" class="btn-close" data-bs-dismiss="alert" data-bs-target="#my-alert" aria-label="Close"></button>

注意，关闭警告框（alert）将导致其从 DOM 中被删除。

方法

You can create an alert instance with the alert constructor, for example:

const bsAlert = new bootstrap.Alert('#myAlert')

This makes an alert listen for click events on descendant elements which have the data-bs-dismiss="alert" attribute. (Not necessary when using the data-api’s auto-initialization.)

Method Description
close Closes an alert by removing it from the DOM. If the .fade and .show classes are present on the element, the alert will fade out before it is removed.
dispose Destroys an element’s alert. (Removes stored data on the DOM element)
getInstance Static method which allows you to get the alert instance associated to a DOM element. For example: bootstrap.Alert.getInstance(alert).
getOrCreateInstance Static method which returns an alert instance associated to a DOM element or create a new one in case it wasn’t initialized. You can use it like this: bootstrap.Alert.getOrCreateInstance(element).

Basic usage:

const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')
alert.close()

本组件所暴露的事件

Bootstrap 的警告框（alert）插件暴露了一些可以监听的事件。

Event Description
close.bs.alert Fires immediately when the close instance method is called.
closed.bs.alert Fired when the alert has been closed and CSS transitions have completed. 
const myAlert = document.getElementById('myAlert')
myAlert.addEventListener('closed.bs.alert', event => {
  // do something, for instance, explicitly move focus to the most appropriate element,
  // so it doesn't get lost/reset to the start of the page
  // document.getElementById('...').focus()
})