跳到主要内容
输入关键词开始搜索，↑ ↓ 选择，Enter 打开
没有找到匹配的文档

轮播

一个滑块或幻灯片组件，用于一次浏览一系列内容，从产品到图片等多种内容。

层级：components
查看原文
本页目录

它是如何工作的

  • 轮播是建立在 CSS 之上的 滚动捕捉所以滑动、触摸拖动、惯性滚动和键盘滚动都由浏览器处理。JavaScript 管理自动播放、上一张/下一张控制、指示器以及活动幻灯片的同步。

  • 因为幻灯片位于一个真正的滚动容器中，所以轮播可以显示 一次多于一张幻灯片显示相邻幻灯片的“预览”，并混合可变宽度的幻灯片——所有这些都可以通过 CSS 控制。

  • 轮播可以有任意数量的幻灯片，里面可以包含几乎任何内容。我们的示例显示了图像和文本，但你可以在每一张幻灯片中放入任何你喜欢的内容 .carousel-item。我们不支持嵌套的轮播。

  • 轮播项目或幻灯片不会标准化它们的尺寸。因此，你可能需要使用额外的工具或自定义样式来适当调整内容的大小。虽然轮播支持上一页/下一页控件和指示器，但它们不是严格必需的。根据需要添加和自定义。

  • 一些行为在任何交互之前需要手动初始化实例，例如页面加载时的自动播放以及用户滚动或滑动时的活动幻灯片同步（指示器只有在实例存在后才开始跟踪可见幻灯片）。 自动播放的轮播 和 data-bs-autoplay="true" 属性在页面加载时会自动初始化；否则，请使用...进行初始化 构造方法如果你正在使用带有数据属性的自动播放轮播， 不要使用构造方法显式地初始化相同的轮播。

  • 标记一张幻灯片 .active 设置起始幻灯片。 它播下了驱动指示器同步的活动状态，并且—— .carousel-fade——显示哪一张幻灯片；如果没有幻灯片 .active，旋转木马从第一个开始。还要确保设置一个唯一的 id 在……上 .carousel 对于可选控件，尤其是当你在单个页面上使用多个轮播时。控件和指示器元素必须具有一个 data-bs-target 属性（或 href 用于链接）与之匹配的 id 的 .carousel 元素。

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

示例

顶部控件

默认的轮播具有一个可以自定义的简单设计。控件可以放置在任何位置，包括轮播内部容器之外。它们可以位于轮播的顶部或底部，并且可以按任何顺序排列控件以及添加任何你可能需要的额外内容。

HTML
<div id="carouselStacked" class="carousel slide">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Top controls</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselStacked" data-bs-slide="prev">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselStacked" data-bs-slide="next">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner rounded-5">
    <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>

底部控制

类似于顶部的控制，但控制位于轮播底部，并且内容不同。

HTML
<div id="carouselStackedBottom" class="carousel slide">
  <div class="carousel-inner rounded-5">
    <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>
    <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselStackedBottom" data-bs-slide="prev">
      <span class="carousel-icon-prev" aria-hidden="true"></span>
      <span class="visually-hidden">Previous</span>
    </button>
    <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselStackedBottom" data-bs-slide="next">
      <span class="carousel-icon-next" aria-hidden="true"></span>
      <span class="visually-hidden">Next</span>
    </button>
  </div>
</div>

指标

在你希望它们存在的任何地方添加指示器按钮。对于覆盖轮播，将它们放置在.carousel-overlay-controls内，该位置位于幻灯片底部之上——它们的确切对齐取决于你如何布置该行（例如，在前/后控制之间居中）。

HTML
<div id="carouselStackedIndicators" class="carousel slide">
  <div class="carousel-inner rounded-5">
    <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 class="d-flex justify-content-between align-items-center">
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselStackedIndicators" data-bs-slide="prev">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselStackedIndicators" data-bs-slide="next">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
    <div class="carousel-indicators">
      <button type="button" data-bs-target="#carouselStackedIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
      <button type="button" data-bs-target="#carouselStackedIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
      <button type="button" data-bs-target="#carouselStackedIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
    </div>
  </div>
</div>

自定义内容

你可以在每个.carousel-item中放入任何标记。添加内容，然后根据需要使用工具或自定义CSS调整大小和样式。

HTML
<div id="carouselExampleContent" class="carousel slide">
  <div class="carousel-inner rounded-5">
    <div class="carousel-item active">
      <div class="d-flex flex-column justify-content-center bg-subtle-primary p-9 bg-1 rounded-5" style="min-height: 320px;">
        <h3>Build anything</h3>
        <p class="fg-emphasis-secondary mb-3">Compose slides from your own markup—text, buttons, cards, or media.</p>
        <div><a class="btn-solid theme-primary" href="#">Get started</a></div>
      </div>
    </div>
    <div class="carousel-item">
      <div class="d-flex flex-column justify-content-center text-center bg-subtle-success p-9 bg-2 rounded-5" style="min-height: 320px;">
        <h3>Style it your way</h3>
        <p class="fg-emphasis-secondary mb-3">Use utilities or custom CSS to size and theme each slide however you need.</p>
        <div><a class="btn-solid theme-success" href="#">Learn more</a></div>
      </div>
    </div>
    <div class="carousel-item">
      <div class="d-flex flex-column justify-content-center text-end bg-subtle-warning p-9 bg-3 rounded-5" style="min-height: 320px;">
        <h3>Mix and match</h3>
        <p class="fg-emphasis-secondary mb-3">Combine custom content with controls, indicators, and the overlay layout.</p>
        <div><a class="btn-solid theme-inverse" href="#">Browse examples</a></div>
      </div>
    </div>
  </div>
  <div class="d-flex justify-content-center gap-2">
    <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselExampleContent" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
      <span class="carousel-icon-prev" aria-hidden="true"></span>
      <span class="visually-hidden">Previous</span>
    </button>
    <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselExampleContent" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
      <span class="carousel-icon-next" aria-hidden="true"></span>
      <span class="visually-hidden">Next</span>
    </button>
  </div>
</div>

修饰符

通过替代控制位置和动画更改默认轮播外观。

覆盖控件

添加 .carousel-overlay 将轮播控制覆盖在幻灯片上。将你想要覆盖的任何控制包装在 .carousel-overlay-controls.

HTML
<div id="carouselExample" class="carousel carousel-overlay slide">
  <div class="carousel-inner rounded-5">
    <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 class="carousel-overlay-controls">
    <div>
      <button class="btn-icon btn-sm btn-subtle theme-secondary" type="button" data-bs-target="#carouselExample" data-bs-slide="prev">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm btn-subtle theme-secondary" type="button" data-bs-target="#carouselExample" data-bs-slide="next">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
    <div class="carousel-indicators">
      <button type="button" data-bs-target="#carouselExample" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
      <button type="button" data-bs-target="#carouselExample" data-bs-slide-to="1" aria-label="Slide 2"></button>
      <button type="button" data-bs-target="#carouselExample" data-bs-slide-to="2" aria-label="Slide 3"></button>
    </div>
  </div>
</div>

交叉淡入淡出

将 .carousel-fade 添加到你的轮播中，以使用淡入淡出过渡来动画幻灯片，而不是滑动过渡。根据你的轮播内容（例如，仅文本的幻灯片），你可能需要将 .bg-body 或一些自定义 CSS 添加到 .carousel-item 上，以实现正确的交叉淡入效果。交叉淡入是一种在 --bs-carousel-fade-duration 上的 CSS 透明度过渡，并且对于偏好减少动画的用户，它会折叠为瞬间切换。

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

物品

因为旋转木马是真正的滚动容器，你可以通过在.carousel上使用一些 CSS 自定义属性来更改可见幻灯片的数量及其大小，而无需编写任何 JavaScript。

  • --bs-carousel-items 设置每个视图中可见的完整幻灯片数量（默认 1）。
  • --bs-carousel-items-gap 设置幻灯片之间的间距（默认 0）。
  • --bs-carousel-items-peek 设置显示相邻幻灯片的程度（默认 0）。

多个项目

将 --bs-carousel-items 设置为一次显示多个幻灯片。将其与 --bs-carousel-items-gap 结合使用以设置间距。

HTML
<div id="carouselMultiple" class="carousel slide" data-bs-ends="stop" style="--bs-carousel-items: 3; --bs-carousel-items-gap: 1rem;">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Three at a time</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselMultiple" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselMultiple" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
  </div>
</div>

将 --bs-carousel-items 内联设置以控制计数，例如 style="--bs-carousel-items: 3;"。

窥视

将 --bs-carousel-items-peek 设置为显示前一张和后一张幻灯片的一小部分，提示还有更多内容可以滚动。

HTML
<div id="carouselPeek" class="carousel slide" data-bs-ends="stop" style="--bs-carousel-items-peek: 3rem; --bs-carousel-items-gap: 1rem;">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Peek the neighbors</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselPeek" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselPeek" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
    <div class="carousel-item"><img src="..." class="d-block w-100 rounded-5" alt="..."></div>
  </div>
</div>

可变宽度

添加 .carousel-auto 并自行设置每个 .carousel-item 的大小（使用工具类或自定义 CSS）。快照点仍然会落在每一张幻灯片上。

HTML
<div id="carouselVariable" class="carousel carousel-auto slide" data-bs-ends="stop" style="--bs-carousel-items-gap: 1rem;">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Mixed widths</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselVariable" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselVariable" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" style="width: 160px;">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item" style="width: 320px;">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item" style="width: 220px;">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item" style="width: 380px;">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item" style="width: 200px;">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item" style="width: 300px;">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
  </div>
</div>

添加 .carousel-center 可将活动幻灯片对齐到视口的中心，而不是起始位置——与 --bs-carousel-items-peek 配合使用效果很好。

自动播放

将 autoplay 选项设置为 true（或添加 data-bs-autoplay="true"）以在页面加载时自动循环轮播。悬停时自动播放会暂停——可通过 pause 选项进行配置——并且在支持 页面可见性 API 的情况下，当页面不可见时也会暂停。只要访客开始控制——点击控件或指示器、使用键盘或滑动——自动播放就会永久停止，以免内容在其操作下被移动。

出于可访问性考虑，我们建议避免使用自动播放的轮播。如果你的页面确实包含轮播，请提供一个可发现的控件来暂停和恢复它：添加一个 .carousel-control-play-pause 按钮（如下所示）。这符合 WCAG 2.2 成功标准 2.2.2 暂停、停止、隐藏，而仅依靠悬停或聚焦来暂停则不符合该标准。

播放/暂停按钮切换自动播放并自动反映当前状态——播放时显示暂停图标，停止时显示播放图标。为每个状态使用data-bs-play-label和data-bs-pause-label属性设置可访问名称。播放时，活动指示器像进度条一样在当前幻灯片的间隔上填充，作为视觉倒计时；自动播放暂停时，指示器也暂停，并在减少动画模式下禁用。使用--bs-carousel-indicator-progress-bg CSS 变量设置其颜色。

HTML
<div id="carouselExampleAutoplaying" class="carousel slide" data-bs-autoplay="true">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
  </div>
  <div class="d-flex justify-content-between align-items-center">
    <div class="carousel-indicators">
      <button type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
      <button type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide-to="1" aria-label="Slide 2"></button>
      <button type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide-to="2" aria-label="Slide 3"></button>
    </div>
    <div>
      <button class="btn-icon btn-sm carousel-control-play-pause" type="button" data-bs-target="#carouselExampleAutoplaying" aria-label="Pause" data-bs-pause-label="Pause" data-bs-play-label="Play">
        <span class="carousel-icon-pause" aria-hidden="true"></span>
        <span class="carousel-icon-play" aria-hidden="true"></span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide="prev">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide="next">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
</div>

单个间隔

将data-bs-interval=""添加到.carousel-item中，以更改自动切换到下一个项目之间的延迟时间。指示器的进度填充与每张幻灯片的间隔相匹配，因此倒计时会相应加快或减慢（下面依次为2秒、4秒、6秒）。

HTML
<div id="carouselExampleInterval" class="carousel slide" data-bs-autoplay="true">
  <div class="carousel-inner rounded-5">
    <div class="carousel-item active" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="4000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="6000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <div class="d-flex justify-content-between align-items-center mt-3">
    <div class="carousel-indicators">
      <button type="button" data-bs-target="#carouselExampleInterval" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
      <button type="button" data-bs-target="#carouselExampleInterval" data-bs-slide-to="1" aria-label="Slide 2"></button>
      <button type="button" data-bs-target="#carouselExampleInterval" data-bs-slide-to="2" aria-label="Slide 3"></button>
    </div>
    <button class="btn-icon btn-sm carousel-control-play-pause" type="button" data-bs-target="#carouselExampleInterval" aria-label="Pause" data-bs-pause-label="Pause" data-bs-play-label="Play">
      <span class="carousel-icon-pause" aria-hidden="true"></span>
      <span class="carousel-icon-play" aria-hidden="true"></span>
    </button>
  </div>
</div>

端行为

ends 选项控制在第一张和最后一张幻灯片上会发生什么。使用 data-bs-ends（或 JavaScript 中的 ends 选项）设置它，从 loop（默认）、wrap 或 stop 中选择。

循环（默认）

当设置为data-bs-ends="loop"时，轮播可以无缝地滚动过头：从最后一张幻灯片向前或从第一张幻灯片向后，都会沿相同方向继续到目标幻灯片，而不是跳回，从而实现无尽的传送带效果。这是默认设置，因此无论是否有该属性都适用。无缝循环适用于通过控件、键盘或自动播放驱动的单张幻灯片轮播；多项布局、预览、居中和可变宽度布局，以及偏好减少动画的用户，则会回退到wrap跳转。

HTML
<div id="carouselEndsLoop" class="carousel slide" data-bs-ends="loop">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Loop</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsLoop" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsLoop" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner rounded-5">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
  </div>
</div>

包裹

当 data-bs-ends="wrap" 时，轮播从最后一张幻灯片跳回到第一张，反之亦然，因此控件永远不会达到终点。

HTML
<div id="carouselEndsWrap" class="carousel slide" data-bs-ends="wrap">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Wrap around</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsWrap" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsWrap" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner rounded-5">
    <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>

停止

与 data-bs-ends="stop" 轮播在第一个和最后一个幻灯片处会硬性停止。在第一个幻灯片上，上一页控制会自动禁用，而在最后一个幻灯片上，下一页控制也会自动禁用（通过原生功能） disabled 属性开启 <button> 控件）；当一个获取焦点的控件被禁用时，焦点会移到相反的控件，以免丢失。

HTML
<div id="carouselEndsStop" class="carousel slide" data-bs-ends="stop">
  <div class="d-flex justify-content-between align-items-center">
    <h5 class="mb-0">Stop at the ends</h5>
    <div>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsStop" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-prev" aria-hidden="true"></span>
        <span class="visually-hidden">Previous</span>
      </button>
      <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsStop" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;">
        <span class="carousel-icon-next" aria-hidden="true"></span>
        <span class="visually-hidden">Next</span>
      </button>
    </div>
  </div>
  <div class="carousel-inner rounded-5">
    <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>

将 data-bs-theme="dark" 添加到 .carousel 以获得更深的控件和指示器。这在使用叠加轮播时通常最有用，当你需要与幻灯片背景形成反向对比时。

HTML
<div id="carouselExampleDark" class="carousel carousel-overlay slide" data-bs-theme="dark">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100 rounded-5" alt="...">
    </div>
  </div>
  <div class="carousel-overlay-controls">
    <button class="btn-icon btn-sm btn-subtle theme-secondary" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev">
      <span class="carousel-icon-prev" aria-hidden="true"></span>
      <span class="visually-hidden">Previous</span>
    </button>
    <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>
    <button class="btn-icon btn-sm btn-subtle theme-secondary" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next">
      <span class="carousel-icon-next" aria-hidden="true"></span>
      <span class="visually-hidden">Next</span>
    </button>
  </div>
</div>

CSS

变量

所有旋转木马的代币：

scss/_carousel.scss
// stylelint-disable-next-line scss/dollar-variable-default
$carousel-tokens: defaults(
  (
    --carousel-gap: .75rem,
    --carousel-indicator-bg: var(--fg-3),
    --carousel-indicator-width: .75rem,
    --carousel-indicator-height: .75rem,
    --carousel-indicator-spacer: .25rem,
    --carousel-indicator-opacity-duration: .6s,
    --carousel-indicator-opacity-timing: ease,
    --carousel-indicator-width-duration: .3s,
    --carousel-indicator-width-timing: ease,
    --carousel-indicator-progress-bg: var(--carousel-indicator-bg),
    --carousel-control-icon-width: 1rem,
    --carousel-control-prev-icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><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: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><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-control-pause-icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path d='M5.5 3.5A1.5 1.5 0 0 1 7 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5m5 0A1.5 1.5 0 0 1 12 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5'/></svg>"),
    --carousel-control-play-icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path d='m11.596 8.697-6.363 3.692c-.54.313-1.233-.066-1.233-.697V4.308c0-.63.692-1.01 1.233-.696l6.363 3.692a.802.802 0 0 1 0 1.393z'/></svg>"),
    // Scroll-snap engine. `gap` must carry a length unit: it feeds the
    // `.carousel-item` flex-basis `calc()`, and subtracting a unitless `0` from a
    // percentage is invalid CSS (it would drop the whole declaration and collapse
    // every slide to its content width). `peek` only feeds `padding-inline`/
    // `scroll-padding-inline`, so a bare `0` would be valid there, but we keep it
    // unit-bearing for consistency.
    --carousel-items: 1,
    --carousel-items-gap: 0px,
    --carousel-items-peek: 0px,
    --carousel-fade-duration: .6s,
    --carousel-fade-timing: ease,
  ),
  $carousel-tokens
);

用法

通过数据属性

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

属性描述
data-bs-autoplay设置为 true 在加载时自动播放轮播。
data-bs-slideprev 或 next 相对于当前幻灯片移动旋转木马。
data-bs-slide-to要显示的幻灯片的零基索引。
data-bs-interval幻灯片之间的自动播放间隔（毫秒）.
data-bs-ends旋转木马在两端的表现： stop, wrap，或者 loop.
data-bs-play-label在一个 .carousel-control-play-pause 按钮，那个 aria-label 在自动播放停止时应用。
data-bs-pause-label在一个 .carousel-control-play-pause 按钮 aria-label 在自动播放进行时应用。

通过 JavaScript

手动调用轮播：

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

依赖项

如果你从源代码构建 Bootstrap 的 JS，轮播插件需要以下 JavaScript 文件：

文件描述
js/src/carousel.ts主轮播组件
js/src/base-component.ts基础组件类
js/src/dom/data.ts元素数据存储
js/src/dom/event-handler.ts事件处理工具
js/src/dom/manipulator.ts数据属性操作
js/src/dom/selector-engine.tsDOM选择器工具
js/src/util/config.ts配置基类
js/src/util/index.ts核心实用功能

选项

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

所有组件都支持一个保留的数据属性 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合并的结果，其中最新提供的键值会覆盖其他键值。

名称类型默认描述
autoplaybooleanfalse如果设置为 true在加载时自动播放轮播。否则，轮播不会自动播放。
endsstring"loop"旋转木马在两端的表现如何。 "stop" 在第一张/最后一张幻灯片处硬性停止——并在第一张幻灯片上禁用上一张控制，在最后一张幻灯片上禁用下一张控制（通过原生） disabled 属性开启 <button> 控制，因此 <a> 控件不受影响）。 "wrap" 从最后一张幻灯片跳回第一张（反之亦然），并且 "loop" 对于单张幻灯片的轮播，滑动无缝地超过末端（回退到 "wrap" 用于多项/预览/居中/可变宽度布局以及在减少动画情况下。
intervalnumber5000在自动循环项目之间延迟的时间量。
keyboardbooleantrue轮播图是否应该对键盘事件作出反应。
pause字符串, 布尔值"hover"如果设置为 "hover"，暂停了旋转木马的循环 mouseenter 并在……上恢复它 mouseleave. 如果设置为 false将鼠标悬停在旋转木马上不会暂停它。

可见幻灯片的数量、它们之间的间距以及相邻幻灯片的预览是通过 CSS 控制的，而不是通过这些选项——请参阅 项目。

方法

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

你可以使用轮播构造函数创建一个轮播实例，并传递任何其他选项。例如，要手动初始化一个自动播放的轮播（假设你没有在标记中使用 data-bs-autoplay="true" 属性）并设置特定的间隔，可以使用：

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

const carousel = new bootstrap.Carousel(myCarouselElement, {
  autoplay: true,
  interval: 2000
})
方法描述
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当新幻灯片滚动到位并稳定后触发（在.carousel-fade中，一旦应用了交叉淡入淡出）。多幻灯片to()跳转可能在滚动经过幻灯片时发出中间slid事件。
slide.bs.carousel当调用slide实例方法时立即触发。
JavaScript
          const myCarousel = document.getElementById('myCarousel')

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