跳至主要内容 跳至文档导航
在 GitHub 上查看

轮播

一个幻灯片组件，用于循环浏览元素（图像或文本幻灯片），就像走马灯一样。

本页内容

工作原理

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

  • 出于性能原因，必须使用 走马灯构造函数方法 手动初始化走马灯。如果没有初始化，一些事件侦听器（特别是需要触控/滑动支持的事件）将不会注册，直到用户明确激活控件或指示器。

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

  • 不支持嵌套走马灯。你还应该意识到，走马灯通常会导致可用性和可访问性方面的挑战。

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

基本示例

以下是包含三张幻灯片的走马灯的基本示例。请注意上一个/下一个控件。我们建议使用 <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 选项进行控制。在支持 页面可见性 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>

深色变体

已在 v5.3.0 中弃用

向 .carousel 添加 .carousel-dark 以获得更深的控件、指示符和标题。与使用 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 时使用自定义样式。如果应用了多个过渡，请确保首先定义变换过渡（例如 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 0z'/></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-.708z'/></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;
$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')

选项

由于选项可以通过数据属性或 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 中给出的值。此外，现有数据属性能够容纳 JSON 值，如 data-bs-delay='{"show":0,"hide":150}'。

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

名称 类型 默认值 说明
interval 数字 5000 在自动循环项目之间延迟的时间量。
键盘 布尔值 true 旋转木马是否应该对键盘事件做出反应。
暂停 字符串、布尔值 "hover" 如果设置为 "hover"，则在 mouseenter 上暂停旋转木马的循环，并在 mouseleave 上恢复旋转木马的循环。如果设置为 false，则将鼠标悬停在旋转木马上方不会暂停它。在支持触控的设备上，当设置为 "hover" 时，循环将在 touchend（用户完成与旋转木马的交互后）暂停两个间隔，然后再自动恢复。这是除了鼠标行为之外的。
骑行 字符串、布尔值 false 如果设置为 true，则在用户手动循环第一个项目后自动播放旋转木马。如果设置为 "carousel"，则在加载时自动播放旋转木马。
触控 布尔值 true 旋转木马是否应该支持触摸屏设备上的左右滑动交互。
包装 布尔值 true 旋转木马是否应该连续循环或硬停。

方法

所有 API 方法都是异步的，并启动一个转换。它们在转换启动后立即返回调用方，但在转换结束之前。此外，将忽略对正在转换的组件的方法调用。 在我们的 JavaScript 文档中了解更多信息。

您可以使用旋转木马构造函数创建一个旋转木马实例，并传递任何其他选项。例如，要手动初始化一个自动播放旋转木马（假设您在标记本身中未使用 data-bs-ride="carousel" 属性），并禁用特定间隔和触控支持，您可以使用

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

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

事件

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

  • 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...
})