跳到主要内容
在 GitHub 查看原文

轮播

一个用于循环显示元素的幻灯片组件——可以是图片或文本幻灯片——类似于轮播。

本页目录

它是如何工作的

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

  • 出于性能原因， 轮播必须手动初始化 使用 轮播构造方法如果不进行初始化，一些事件监听器（特别是需要触摸/滑动支持的事件）将不会被注册，直到用户明确激活某个控件或指示器。

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

  • 不支持嵌套轮播。你还应该注意，轮播通常会引起可用性和可访问性的问题。

此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们的无障碍文档中的减少动画部分。

基本示例

这是一个有三个幻灯片的轮播的基本示例。请注意前一张/下一张控件。我们建议使用 <button> 元素，但你也可以使用 <a> 带有……的元素 role="button".

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 将类分配到其中一张幻灯片否则轮播将不可见。还要确保设置一个唯一的 id 在……上 .carousel 对于可选控件，尤其是当你在单个页面上使用多个轮播时。控件和指示器元素必须具有一个 data-bs-target 属性（或 href 用于链接）与之匹配的 id 的 .carousel 元素。

指标

你可以在轮播图上添加指示器，同时保留上一个/下一个控件。指示器让用户可以直接跳转到特定的幻灯片。

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-caption 任何中的元素 .carousel-item它们可以像下面显示的那样在较小的视口上轻松隐藏，并且是可选的 显示工具我们最初用…隐藏它们 .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 到你的轮播中，用淡入淡出过渡来动画幻灯片，而不是滑动。根据你的轮播内容（例如，仅文字的幻灯片），你可能想要添加 .bg-body 或者一些自定义CSS到 .carousel-item用于适当的交叉淡入淡出。

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选项进行控制。在支持页面可见性 API的浏览器中，当网页对用户不可见时（例如浏览器标签页不活跃或浏览器窗口最小化时），轮播将停止循环。

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

参见 WCAG 2.2 成功准则 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>

将 data-bs-interval="" 添加到 .carousel-item 来更改自动切换到下一个项目之间的延迟时间。

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>

深色变体

在 v5.3.0 中弃用

将 .carousel-dark 添加到 .carousel 以获得更暗的控件、指示器和字幕。控件相对于默认的白色填充使用 filter CSS 属性进行反转。字幕和控件有额外的 Sass 变量，可自定义 color 和 background-color。

注意！ 随着颜色模式的引入，组件的深色变体在 v5.3.0 中已被弃用。不要添加 .carousel-dark，请在根元素、父包装元素或组件本身上设置 data-bs-theme="dark"。

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-item 的过渡持续时间可以在编译前通过 $carousel-transition-duration Sass 变量更改，或者如果你使用的是已编译的 CSS，则可以通过自定义样式更改。如果应用了多个过渡，请确保先定义 transform 过渡（例如 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-control-icon-filter:       null;

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

深色轮播的变量：

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

用法

通过数据属性

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

通过 JavaScript

手动调用轮播：

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

选项

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

从 Bootstrap 5.2.0 开始，所有组件都支持一个 实验性的保留数据属性 data-bs-config，它可以用作存放简单组件配置的 JSON 字符串。当一个元素同时拥有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 属性时，最终的 title 值将会是 456，且单独的数据属性将覆盖 data-bs-config 上给定的值。此外，现有的数据属性也能够存放如 data-bs-delay='{"show":0,"hide":150}' 的 JSON 值。

最终的配置对象是data-bs-config、data-bs-和js object合并的结果，其中最新提供的键值会覆盖其他键值。

名称类型默认值描述
intervalnumber5000在自动循环一个项目之间的延迟时间。
keyboardbooleantrue轮播图是否应该对键盘事件作出反应。
pause字符串, 布尔值"hover"如果设置为 "hover"，暂停了轮播的循环 mouseenter 并恢复轮播的循环 mouseleave. 如果设置为 false，将鼠标悬停在轮播上不会暂停它。在支持触摸的设备上，当设置为 "hover"，骑行将暂停 touchend （一旦用户完成与轮播的互动）暂停两个间隔，然后自动恢复。这是对鼠标行为的补充。
ride字符串, 布尔值false如果设置为 true在用户手动切换第一个项目后，会自动播放轮播。如果设置为 "carousel"加载时自动播放轮播。
touchbooleantrue轮播是否应支持触摸屏设备上的左右滑动交互。
wrapbooleantrue轮播是否应该连续循环或有明显的停止点。

方法

所有 API 方法都是异步的并启动一次过渡。 它们在过渡开始后立即返回给调用者，但在过渡结束之前。此外，对正在过渡的组件进行的方法调用将被忽略。 在我们的 JavaScript 文档中了解更多信息。

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

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

const carousel = new bootstrap.Carousel(myCarouselElement, {
interval: 2000,
touch: false
})

方法描述
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 的轮播（carousel）类提供了两个事件，用于挂钩轮播功能。这两个事件具有以下附加属性：

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

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

事件类型描述
slid.bs.carousel当轮播完成滑动过渡时触发。
slide.bs.carousel在调用 slide 实例方法时立即触发。
const myCarousel = document.getElementById('myCarousel')

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