在GitHub上查看

轮播效果

一个幻灯片组件，用于在元素、图像或文本幻灯片（如轮播图）之间循环。

本页导航↓

工作原理

该轮播是一个幻灯片，用于循环显示一系列内容，这些内容使用CSS 3D转换和一些JavaScript构建。 它适用于一系列图像，文本或自定义标记。 它还包括对上一个/下一个控件和指示器的支持。

在支持页面 可见性API的浏览器中，当用户看不到网页时（如浏览器选项卡处于非活动状态、浏览器窗口最小化等），轮播图将避免滑动。

此组件的动画效果取决于 prefers-reduced-motion 查询。请参阅我们的可访问的文档 的简化运动部分。

请注意，不支持嵌套轮播图，轮播图通常不符合可访问性标准。

示例

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

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

仅有轮播图

这是只带有幻灯片的轮播图。 请注意，轮播图片上存在 .d-block 和 .w-100，以防止浏览器默认图片对齐。

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

带有控件的轮播图

添加上一个和下一个控件：

<div id="carouselExampleControls" 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>
<a class="carousel-control-prev" href="#carouselExampleControls" role="button" data-bs-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="visually-hidden">Previous</span>
</a>
<a class="carousel-control-next" href="#carouselExampleControls" role="button" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</a>
</div>

带有指示的轮播图

您还可以将指示器添加到轮播图，以及控件旁边。

<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="carousel">
<ol class="carousel-indicators">
<li data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active"></li>
<li data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1"></li>
<li data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2"></li>
</ol>
<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>
<a class="carousel-control-prev" href="#carouselExampleIndicators" role="button" data-bs-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="visually-hidden">Previous</span>
</a>
<a class="carousel-control-next" href="#carouselExampleIndicators" role="button" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</a>
</div>

带有文字的轮播图

在任何 .carousel-item 中使用 .carousel-caption 元素，可以轻松地将字幕添加到幻灯片中。 可以使用可选的显示实用工具 将它们轻松隐藏在较小的视口中，如下所示。 我们最初将其隐藏为 .d-none ，然后将其恢复为带有 .d-md-block 的中型设备。 

<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
<ol class="carousel-indicators">
<li data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active"></li>
<li data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1"></li>
<li data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2"></li>
</ol>
<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>Nulla vitae elit libero, a pharetra augue mollis interdum.</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>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</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>Praesent commodo cursus magna, vel scelerisque nisl consectetur.</p>
  </div>
</div>
</div>
<a class="carousel-control-prev" href="#carouselExampleCaptions" role="button" data-bs-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="visually-hidden">Previous</span>
</a>
<a class="carousel-control-next" href="#carouselExampleCaptions" role="button" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</a>
</div>

淡入淡出的轮播图

将 .carousel-fade 添加到您的幻灯片以使用淡入淡出过渡（而不是幻灯片）设置幻灯片动画。

<div id="carouselExampleFade" class="carousel slide carousel-fade" 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>
<a class="carousel-control-prev" href="#carouselExampleFade" role="button" data-bs-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="visually-hidden">Previous</span>
</a>
<a class="carousel-control-next" href="#carouselExampleFade" role="button" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</a>
</div>

将数据 data-bs-interval="" 添加到 .carousel-item 以更改自动循环到下一项之间的延迟时间量。

<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>
<a class="carousel-control-prev" href="#carouselExampleInterval" role="button" data-bs-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="visually-hidden">Previous</span>
</a>
<a class="carousel-control-next" href="#carouselExampleInterval" role="button" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</a>
</div>

深色轮播图

将 .carousel-dark 添加到 .carousel 以获得较深色的控件、指示器和标题。控件已使用 filter CSS属性从其默认的白色填充进行反转。标题和控件具有自定义 color 和 background-color的附加Sass变量。

<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
<ol class="carousel-indicators">
<li data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active"></li>
<li data-bs-target="#carouselExampleDark" data-bs-slide-to="1"></li>
<li data-bs-target="#carouselExampleDark" data-bs-slide-to="2"></li>
</ol>
<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>Nulla vitae elit libero, a pharetra augue mollis interdum.</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>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</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>Praesent commodo cursus magna, vel scelerisque nisl consectetur.</p>
  </div>
</div>
</div>
<a class="carousel-control-prev" href="#carouselExampleDark" role="button" data-bs-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="visually-hidden">Previous</span>
</a>
<a class="carousel-control-next" href="#carouselExampleDark" role="button" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</a>
</div>

用法

通过数据属性

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

data-bs-ride="carousel" 属性用于在页面加载时将轮播图标记为动画。如果不使用 data-bs-ride="carousel" 来初始化carousel，则必须自己初始化它。它不能与同一个carousel的显式JavaScript初始化（冗余和不必要的）结合使用。

通过 JavaScript

手动调整：

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel)

选项

选项可以通过数据属性或JavaScript传递。对于数据属性，将选项名称追加到 data-bs-，如 data-bs-interval=""。

名称 类型 默认 描述
interval number 5000 在延迟时间过后自动循环轮播图片。如果为 false, 则轮播不会自动循环。
keyboard boolean true 轮播是否应该对键盘事件做出反应。
pause string | boolean "hover"

如果设置为 "hover"，则暂停在 mouseenter 上的轮播循环，并在 mouseleave 上恢复轮播的循环。 如果设置为 false，则将鼠标悬停在转盘上不会暂停它。

在支持触摸的设备上，当设置为 "hover" 时，循环将在 touchend 上暂停两段时间（一旦用户完成与转盘的交互），然后自动恢复。请注意，这是对上述鼠标行为的补充。

slide string | boolean false 用户手动循环第一项后，自动播放轮播。 如果为“轮播”，则在加载时自动播放轮播图。
wrap boolean true 轮播是否应该连续循环或强行停止。
touch boolean true 轮播是否应支持触摸屏设备上的向左/向右滑动交互。

方法

异步方法和转换

所有API方法都是异步的，并开始转换。它们在转换一开始就返回给调用者，但在转换结束之前。此外，对转换组件的方法调用将被忽略。

有关更多信息，请参阅我们的JavaScript文档。

您可以使用carousel构造函数创建一个轮播图实例，例如，使用其他选项初始化并开始在项之间循环：

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel, {
interval: 2000,
wrap: false
})
方法 描述
cycle 从左到右循环播放轮播项目。
pause 阻止轮播在各个项目之间循环。
prev 循环到上一个项目。 在显示上一个项目之前 （例如，在 slid.bs.carousel 事件发生 之前）返回到调用方。
next 循环到下一个项目。 在显示下一项之前（例如，在 slid.bs.carousel 事件发生之前）返回到调用方。
nextWhenVisible 当页面不可见或轮播或其父项不可见时，请勿将轮播循环到下一个。 在显示目标项目之前返回调用者
to 将轮播循环到特定帧（从0开始，类似于数组）。 在显示目标项目之前（例如，在 slid.bs.carousel 事件发生之前）返回到调用方。
dispose 销毁元素的轮播。 （删除DOM元素上存储的数据）
getInstance 允许您获取与DOM元素关联的轮播实例的静态方法。

事件

Bootstrap的carousel类声明了两个用于挂接到carousel功能的事件。这两个事件都具有以下附加属性：

  • direction: 轮播图滑动的方向 ( "left" 或者 "right").
  • relatedTarget: 作为活动项滑动到适当位置的DOM元素。
  • from: 当前项的索引
  • to: 下一项的索引

所有滑动事件都会在轮播图本身触发 (即在 <div class="carousel"> 处)

事件类型 描述
slide.bs.carousel 调用 slide 实例方法时立即触发。
slid.bs.carousel 轮播完成幻灯片切换后触发。 
var myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', function () {
// do something...
})

更改过渡时间

.carousel-item 的转换持续时间可以在编译前使用 $carousel-transition Sass变量更改，如果使用已编译的CSS，则可以使用自定义样式更改。如果应用了多个变换，请确保首先定义变换变换。（例如过渡：转换2s转化，不透明度0.5s转化）。