Bootstrap V5.3 : Carousel 轮播图中文翻译版

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

运作方式

轮播是一个幻灯片，用于循环浏览一系列内容，使用 CSS 3D 转换和一些 JavaScript 构建。它适用于一系列图像、文本或自定义标记。它还包括对上一个/下一个控件和指示器的支持。
出于性能原因，必须使用轮播构造函数方法手动初始化轮播。如果不进行初始化，则在用户显式激活控件或指示器之前，不会注册某些事件侦听器（特别是需要触摸/滑动支持的事件）。

唯一的例外是使用属性自动播放轮播，因为这些轮播是在页面加载时自动初始化的。如果您使用带有 data 属性的自动播放轮播，请不要使用构造函数方法显式初始化相同的轮播。data-bs-ride="carousel"
不支持嵌套轮播。您还应该注意，轮播通常会导致可用性和可访问性挑战。

此组件的动画效果取决于媒体查询。请参阅我们的辅助功能文档的减少运动部分。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.carouseldata-bs-targethrefid.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

第一张幻灯片标签

第一张幻灯片的一些代表性占位符内容。

Second slide label

Some representative placeholder content for the second slide.

Third slide label

Some representative placeholder content for the third slide.

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

交叉淡入淡出

添加到轮播中，以使用淡入淡出过渡而不是幻灯片来制作幻灯片动画。根据轮播内容（例如，纯文本幻灯片），您可能需要在 s 中添加或一些自定义 CSS 以进行适当的交叉淡入淡出。.carousel-fade.bg-body.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>

自动播放轮播

您可以通过将选项设置为来使轮播在页面加载时自动播放。自动播放轮播在鼠标悬停时会自动暂停。可以使用选项控制此行为。在支持页面可见性 API 的浏览器中，当网页对用户不可见时（例如，当浏览器选项卡处于非活动状态或浏览器窗口最小化时），轮播将停止循环。ridecarouselpause

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

请参阅 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>

当该选项设置为而不是时，轮播不会在页面加载时自动开始循环。相反，它只会在第一次用户交互后启动。ridetruecarousel

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

添加到 a 以更改自动循环到下一个项目之间的延迟时间。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>

禁用触摸滑动

轮播支持在触摸屏设备上向左/向右滑动以在幻灯片之间移动。可以通过将选项设置为来禁用此功能。touchfalse

[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 中已弃用

添加到以获得较暗的控件、指示符和字幕。控件与带有 CSS 属性的默认白色填充相比是反转的。字幕和控件具有额外的 Sass 变量，用于自定义和。.carousel-dark.carouselfiltercolorbackground-color

小心！随着颜色模式的引入，组件的深色变体在 v5.3.0 中被弃用。而不是在根元素上添加，而是在根元素上设置一个父元素包装器或组件本身。.carousel-darkdata-bs-theme="dark"

第一张幻灯片标签

第一张幻灯片的一些代表性占位符内容。

Second slide label

Some representative placeholder content for the second slide.

Third slide label

Some representative placeholder content for the third slide.

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

自定义过渡

如果你使用的是编译的 CSS，可以在编译前使用 Sass 变量或自定义样式来更改的过渡持续时间。如果应用了多个过渡，请确保首先定义变换过渡（例如）。.carousel-item$carousel-transition-durationtransition: 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-slideprevnextdata-bs-slide-todata-bs-slide-to="2"0

通过 JavaScript

使用以下功能手动调用轮播：

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

选项

由于选项可以通过数据属性或 JavaScript 传递，因此您可以将选项名称附加到，如。通过数据属性传递选项时，请确保将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用代替。data-bs-data-bs-animation="{value}"data-bs-custom-class="beautifier"data-bs-customClass="beautifier"

从 Bootstrap 5.2.0 开始，所有组件都支持实验性保留数据属性，该属性可以将简单的组件配置作为 JSON 字符串容纳。当元素具有和属性时，最终值将是，并且单独的数据属性将覆盖上给出的值。此外，现有数据属性能够容纳 JSON 值，例如 .data-bs-configdata-bs-config='{"delay":0, "title":123}'data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

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

名字	类型	违约	描述
`interval`	数	`5000`	自动循环项目之间的延迟时间量。
`keyboard`	布尔	`true`	轮播是否应对键盘事件做出反应。
`pause`	字符串，布尔值	`"hover"`	如果设置为，则会暂停轮播的循环，并恢复轮播的循环。如果设置为，将鼠标悬停在轮播上不会暂停它。在支持触摸的设备上，如果设置为，循环将暂停（用户完成与轮播的交互后）两个间隔，然后自动恢复。这是对鼠标行为的补充。`"hover"mouseentermouseleavefalse"hover"touchend`
`ride`	字符串，布尔值	`false`	如果设置为，则在用户手动循环第一个项目后自动播放轮播。如果设置为，则在加载时自动播放轮播。`true"carousel"`
`touch`	布尔	`true`	轮播是否应支持触摸屏设备上的左/右滑动交互。
`wrap`	布尔	`true`	旋转木马是应该连续循环还是硬停止。

方法

所有 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...
})

Bootstrap V5.3 中文手册

入门指南 Getting started

定制化 Customize

布局方式 Layout

内容样式 Content

表单控件 Forms

组件集合 Components

辅助工具 Helpers

工具类库 Utilities

功能扩展 Extend

关于Bootstrap

Carousel 轮播图

运作方式

基本示例

指标

字幕

第一张幻灯片标签

Second slide label

Third slide label

交叉淡入淡出

自动播放轮播

个人间隔`.carousel-item`

自动播放没有控件的轮播

禁用触摸滑动

深色变体

第一张幻灯片标签

Second slide label

Third slide label

自定义过渡

CSS系统

Sass 变量

用法

通过数据属性

通过 JavaScript

选项

方法

事件

Carousel 轮播图

运作方式

基本示例

指标

字幕

第一张幻灯片标签

Second slide label

Third slide label

交叉淡入淡出

自动播放轮播

个人间隔.carousel-item

自动播放没有控件的轮播

禁用触摸滑动

深色变体

第一张幻灯片标签

Second slide label

Third slide label

自定义过渡

CSS系统

Sass 变量

用法

通过数据属性

通过 JavaScript

选项

方法

事件

个人间隔`.carousel-item`