Skip to main content Skip to docs navigation
View on GitHub

轮播（Carousel）

幻灯片组件，用于循环播放元素–图像或文本幻灯片，就像轮播一样。

On this page

工作原理

  • 轮播是一种用于循环播放一系列内容的幻灯片，使用 CSS 3D 变换和少量 JavaScript 构建。它可以使用一系列图片、文本或自定义标记。它还支持上一个/下一个控件和指示器。

  • 出于性能考虑，必须使用轮播构造函数方法 手动初始化 轮播。如果不进行初始化，在用户明确激活控件或指示器之前，某些事件监听器（特别是需要触摸/擦拭支持的事件）将不会被注册。

    唯一的例外是带有 data-bs-ride="carousel" 属性的自动播放轮播，因为它们会在页面加载时自动初始化。如果您使用的是带有 data 属性的自动播放轮播，不要使用构造方法明确初始化相同的轮播 。

  • 不支持嵌套轮播。您还应该注意，轮播通常会对可用性和可访问性造成挑战。

The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation.

基本示例

下面是一个有三个幻灯片的轮播的基本示例。注意上一个/下一个控件。我们建议使用 <button> 元素，但也可以使用具有 role="button" 的 <a> 元素。

html 
<div id="carouselExample" class="carousel slide">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExample" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExample" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

轮播不会自动调整幻灯片尺寸。因此，您可能需要使用其他实用程序或自定义样式来适当调整内容的尺寸。虽然轮播支持上一个/下一个控件和指示器，但并非明确要求。请根据自己的需要添加和自定义。

您必须在其中一张幻灯片上添加.active类， 否则轮播将不可见。此外，请确保为可选控件在.carousel上设置一个唯一的id，尤其是在一个页面上使用多个轮播的情况下。控件和指示器元素必须具有与.carousel元素的id相匹配的data-bs-target属性（或链接的href属性）。

指标

您可以在轮播的上一个/下一个控件旁边添加指示器。指示器可让用户直接跳转到特定幻灯片。

html 
<div id="carouselExampleIndicators" class="carousel slide">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

说明文字

您可以在任何".carousel-item"中使用".carousel-caption"元素为幻灯片添加说明文字。如下图所示，通过可选的显示实用程序，可以在较小的视口上轻松隐藏说明文字。我们最初使用 .d-none 隐藏它们，然后在中型设备上使用 .d-md-block 恢复它们。

html 
<div id="carouselExampleCaptions" class="carousel slide">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

淡入淡出

在轮播中添加".carousel-fade"，以渐变过渡代替幻灯片动画。根据轮播的内容（如纯文本幻灯片），您可能需要在.carousel-item中添加.bg-body或一些自定义 CSS，以实现正确的交叉淡入淡出。

html 
<div id="carouselExampleFade" class="carousel slide carousel-fade">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

自动轮播

通过将 ride 选项设置为 carousel，可以使轮播在页面加载时自动播放。当鼠标悬停时，自动播放的轮播会自动暂停。可以使用pause选项控制这种行为。在支持 Page Visibility API的浏览器中，当用户看不到网页时（如浏览器标签处于非活动状态或浏览器窗口最小化），轮播将停止循环。

出于可访问性的考虑，我们建议避免使用自动播放的轮播。如果您的页面确实包含自动播放的轮播，我们建议您提供一个额外的按钮或控件来明确暂停/停止轮播。

参见 WCAG 2.1 成功准则 2.2.2 暂停、停止、隐藏。

html 
<div id="carouselExampleAutoplaying" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

当 ride 选项设置为true而不是 carousel 时，轮播在页面加载时自动开始循环。相反，它只会在第一次用户交互后启动。

html 
<div id="carouselExampleRide" class="carousel slide" data-bs-ride="true">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleRide" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleRide" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

在.carousel-item中添加data-bs-interval=""，以更改自动循环到下一个项目之间的延迟时间。

html 
<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

不带控件的自动播放轮播

下面是一个只有幻灯片的轮播。请注意，轮播图像上存在 .d-block 和 .w-100，以防止浏览器默认的图像对齐方式。

html 
<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
</div>

禁用触摸轻扫

轮播支持在触摸屏设备上左右滑动以在幻灯片之间移动。将 touch 选项设置为 false 即可禁用该功能。

html 
<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

深色变体

Deprecated in v5.3.0

在 .carousel中添加 .carousel-dark，使控件、指示器和标题颜色更深。控件会使用 filter CSS 属性反转其默认的白色填充。标题和控件具有额外的 Sass 变量，可自定义color和background-color。

Heads up! Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of adding .carousel-dark, set data-bs-theme="dark" on the root element, a parent wrapper, or the component itself.

html 
<div id="carouselExampleDark" class="carousel carousel-dark slide">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

自定义过渡

在编译之前，可使用 $carousel-transition-duration Sass 变量更改.carousel-item的过渡持续时间；如果使用编译后的 CSS，则可使用自定义样式。如果应用了多个过渡，请确保首先定义了转换过渡（例如，transition: transform 2s ease, opacity .5s ease-out）。

CSS

Sass 变量

适用于所有轮播的变量：

scss/_variables.scss 
$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;

$carousel-indicator-width:           30px;
$carousel-indicator-height:          3px;
$carousel-indicator-hit-area-height: 10px;
$carousel-indicator-spacer:          3px;
$carousel-indicator-opacity:         .5;
$carousel-indicator-active-bg:       $white;
$carousel-indicator-active-opacity:  1;
$carousel-indicator-transition:      opacity .6s ease;

$carousel-caption-width:             70%;
$carousel-caption-color:             $white;
$carousel-caption-padding-y:         1.25rem;
$carousel-caption-spacer:            1.25rem;

$carousel-control-icon-width:        2rem;

$carousel-control-prev-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0'/></svg>");
$carousel-control-next-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708'/></svg>");

$carousel-transition-duration:       .6s;
$carousel-transition:                transform $carousel-transition-duration ease-in-out; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`)

深色 carousel 的变量:

scss/_variables.scss 
$carousel-dark-indicator-active-bg:  $black;
$carousel-dark-caption-color:        $black;
$carousel-dark-control-icon-filter:  invert(1) grayscale(100);

用法

通过数据属性

使用数据属性可轻松控制轮播的位置。data-bs-slide 接受关键字 prev 或 next，可改变幻灯片相对于当前位置的位置。或者，使用 data-bs-slide-to 将原始幻灯片索引传递给轮播 data-bs-slide-to="2"，这会将幻灯片位置移动到以 0 开头的特定索引。

通过 JavaScript

手动调用轮播:

const carousel = new bootstrap.Carousel('#myCarousel')

选项

由于可以通过 data 属性或 JavaScript 传递选项，因此可以在 data-bs- 中附加选项名称，如 data-bs-animation=“{value}”。通过data 属性传递选项时，请确保将选项名称的大小写类型从“camelCase”改为“kebab-case”。例如，使用 data-bs-custom-class=“beautifier” 而不是 data-bs-customClass=“beautifier”。

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

Name Type Default Description
interval number 5000 项目自动循环之间的延迟时间。
keyboard boolean true 轮播是否应对键盘事件做出反应。
pause string, boolean "hover" 如果设置为"hover"，则在 mouseenter时暂停轮播的循环，并在 mouseleave 时恢复轮播的循环。如果设置为 false，则鼠标悬停在轮播上时不会暂停。在支持触摸的设备上，当设置为 “hover"时，在 touchend 时（一旦用户完成与轮播的交互），循环将暂停两次，然后自动恢复。这是对鼠标行为的补充。
ride string, boolean false 如果设置为 true，则在用户手动循环第一个项目后自动播放轮播。如果设置为 carousel，则在加载时自动播放轮播。
touch boolean true 在触摸屏设备上，轮播是否应支持左右滑动交互。
wrap boolean true 轮播是连续循环还是硬停止。

方法

所有 API 方法都是异步的，并且会启动一个过渡，它们会在过渡开始后、结束前返回给调用者。此外，对过渡组件的方法调用将被忽略。更多信息，请参阅 JavaScript 文档

您可以使用轮播构造函数创建一个轮播实例，并传递任何附加选项。例如，要手动初始化一个自动播放的轮播（假设您没有在标记中使用 data-bs-ride="carousel" 属性），并设定一个特定的时间间隔，同时禁用触摸支持，您可以使用以下方法：

const myCarouselElement = document.querySelector('#myCarousel')

const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  touch: false
})
Method Description
cycle 开始从左到右循环浏览轮播项目。
dispose 销毁元素的轮播。（删除 DOM 元素上存储的数据）
getInstance 静态方法，用于获取与 DOM 元素相关联的轮播实例。您可以这样使用它 bootstrap.Carousel.getInstance(element)。
getOrCreateInstance 静态方法，用于返回与 DOM 元素相关联的轮播实例，或在未初始化的情况下创建一个新实例。可以这样使用 bootstrap.Carousel.getOrCreateInstance(element)。
next 循环显示下一个项目。在下一个项目显示之前 返回给调用者（例如，在 slid.bs.carousel 事件发生之前）。
nextWhenVisible 当页面、轮播或轮播的父层不可见时，不将轮播循环到下一个。在目标项目显示之前返回调用者。
pause 停止轮播循环播放项目。
prev 循环到上一个项目。在显示上一个项目之前 返回调用者（例如，在发生 slid.bs.carousel 事件之前）。
to 将轮播循环到特定帧（基于 0，类似于数组）。在显示目标项目之前 返回调用者（例如，在 slid.bs.carousel 事件发生之前）。

事件

Bootstrap 的轮播类公开了两个事件，用于挂接轮播功能。这两个事件都有以下附加属性：

  • 方向： 轮播滑动的方向（"left"或 "right"）。
  • relatedTarget： 作为活动项目滑动到位的 DOM 元素。
  • from： 当前项目的索引
  • to： 下一个项目的索引

所有轮播事件都是在轮播本身（即在 <div class="carousel"> 处）触发的。

Event type Description
slid.bs.carousel 当轮播完成滑动过渡时触发。
slide.bs.carousel 当调用 slide 实例方法时立即触发。 
const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // do something...
})