Skip to main content Skip to docs navigation
View on GitHub

警告框(Alert)

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

示例

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

<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)(初始是隐藏的,添加了内联样式),然后点击关闭按钮将其关闭(并销毁)。

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

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

var alertPlaceholder = document.getElementById('liveAlertPlaceholder')
var alertTrigger = document.getElementById('liveAlertBtn')

function alert(message, type) {
  var wrapper = document.createElement('div')
  wrapper.innerHTML = '<div class="alert alert-' + type + ' alert-dismissible" role="alert">' + message + '<button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button></div>'

  alertPlaceholder.append(wrapper)
}

if (alertTrigger) {
  alertTrigger.addEventListener('click', function () {
    alert('Nice, you triggered this alert message!', 'success')
  })
}

链接的颜色

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

<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 元素,例如标题、段落、分割线等。

<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)。针对你所选的图标和内容,你需要为其设置更多的工具类或自定义样式。

<div class="alert alert-primary d-flex align-items-center" role="alert">
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="currentColor" 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,这样可以方便重复地引用相同的图标。

<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
  <symbol id="check-circle-fill" fill="currentColor" 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" fill="currentColor" 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" fill="currentColor" 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" width="24" height="24" 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" width="24" height="24" 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" width="24" height="24" 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" width="24" height="24" 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

以下是演示效果:

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

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

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

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

@mixin alert-variant($background, $border, $color) {
  --#{$variable-prefix}alert-color: #{$color};
  --#{$variable-prefix}alert-bg: #{$background};
  --#{$variable-prefix}alert-border-color: #{$border};

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

  .alert-link {
    color: shade-color($color, 20%);
  }
}

Sass loop

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

// Generate contextual modifier classes for colorizing the alert.

@each $state, $value in $theme-colors {
  $alert-background: shift-color($value, $alert-bg-scale);
  $alert-border: shift-color($value, $alert-border-scale);
  $alert-color: shift-color($value, $alert-color-scale);

  @if (contrast-ratio($alert-background, $alert-color) < $min-contrast-ratio) {
    $alert-color: mix($value, color-contrast($alert-background), abs($alert-color-scale));
  }
  .alert-#{$state} {
    @include alert-variant($alert-background, $alert-border, $alert-color);
  }
}

JavaScript 行为

初始化

将 DOM 元素初始化为警告框(alert)

var alertList = document.querySelectorAll('.alert')
var alerts = Array.prototype.slice.call(alertList).map(function (element) {
  return 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 中被删除。

方法

方法 描述
close 关闭警告框(alert)并从 DOM 中将其删除。如果改元素被设置了 .fade.show 类的话,则警告框(alert)将在被删除之前展示逐渐消散(fade out)的效果。
dispose 销毁某个元素的警告框(alert)。 (并删除存储在该 DOM 元素上的数据)
getInstance 此静态方法允许你获取与 DOM 元素相关的警告框(alert)实例,调用方式为: bootstrap.Alert.getInstance(alert)
getOrCreateInstance 静态方法,该方法返回一个与 DOM 元素关联的警告框(alert)实例,如果还未初始化的话,将创建一个新实例。 你可以像这样使用该方法: bootstrap.Alert.getOrCreateInstance(element)
var alertNode = document.querySelector('.alert')
var alert = bootstrap.Alert.getInstance(alertNode)
alert.close()

本组件所暴露的事件

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

事件 描述
close.bs.alert close 实例方法被调用时,该事件被立即触发。
closed.bs.alert 当警告框(alert)已关闭并且 CSS transitions 执行完时,该事件兼备触发。
var myAlert = document.getElementById('myAlert')
myAlert.addEventListener('closed.bs.alert', function () {
  // 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()
})