跳到主题内容 跳到文档导航栏

轮播(Carousel)

幻灯片组件，用于循环显示元素（图像或文本幻灯片），例如轮播。

在本页面

怎样工作

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

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

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

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

示例

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

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

仅幻灯片

这是一个只有幻灯片的轮播。注意 carousel图像上存在.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添加到您的carousel以使用淡入淡出过渡，而不是幻灯片设置幻灯片动画。

<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以获得较深色的控件、指示器和标题。控件已使用 filterCSS属性从其默认白色填充反转。字幕和控件有额外的Sass变量，可以自定义color 和 background-color。

<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将原始幻灯片索引传递给carousel data-bs-slide-to="2"，从而将幻灯片位置移动到从0开始的特定索引。

data-bs-ride="carousel"属性用于将carousel标记为从页面加载开始设置动画。如果您不使用data-bs-ride="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，carousel将不会自动循环。
keyboard boolean true 轮播是否应对键盘事件作出反应。
pause string | boolean "hover"

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

在支持触摸的设备上，当设置为"hover"时，循环将在touchend上暂停两段时间（一旦用户完成与轮播的交互），然后自动恢复。请注意，这是对上述鼠标行为的补充。
slide string | boolean false 用户手动循环第一个项目后自动播放轮播。如果是 "carousel"，则在加载时自动放置carousel。
wrap boolean true 轮播应连续循环还是硬停止。
touch boolean true 轮播是否应支持触摸屏设备上的左/右滑动交互。

方法

异步方法和转换

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

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

例如，您可以使用carousel构造函数创建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元素关联的carousel实例。

事件

Bootstrap的carousel类公开了两个事件，用于连接到carousel功能。两个事件都具有以下附加属性：

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

所有carousel事件都在carousel本身触发（即在<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-transitionSass变量更改，如果使用已编译的CSS，则可以使用自定义样式更改。如果应用了多个变换，请确保首先定义变换变换（例如，transition: transform 2s ease, opacity .5s ease-out）。