bootstrap_ref_js_carousel

Bootstrap JS 轮播

JS 轮播 (carousel.js)

轮播（Carousel）插件是一个用于循环显示元素（例如幻灯片）的组件。它使用 CSS 3D 变换和 JavaScript 构建，需要 Bootstrap JavaScript 库（bootstrap.bundle.min.js，其中包含 Popper，或单独的文件）。

要了解有关轮播的循序渐进教程，请阅读我们的 Bootstrap 轮播教程。

注意：轮播通常在支持 CSS3 过渡和动画的现代浏览器中得到良好支持。不支持嵌套轮播。

轮播插件类

类名	描述
.carousel	轮播的主容器。
.carousel-inner	幻灯片（.carousel-item 元素）的容器。
.carousel-item	定义轮播中的单个幻灯片。其中一个项目必须包含 .active 类。
.carousel-item.active	指示当前可见的幻灯片。
.carousel-control-prev	添加一个“上一张”按钮用于导航幻灯片。
.carousel-control-next	添加一个“下一张”按钮用于导航幻灯片。
.carousel-control-prev-icon	“上一张”按钮的图标（通常是 SVG）。
.carousel-control-next-icon	“下一张”按钮的图标（通常是 SVG）。
.carousel-indicators	幻灯片指示器（小圆点）的容器。每个指示器都是 <button> 元素。
.carousel-caption	.carousel-item 内可选标题的容器。
.carousel-fade	添加到 .carousel 可使幻灯片以淡入淡出过渡而不是滑动动画。

通过 data-* 属性

Bootstrap 轮播可以完全通过 data 属性控制：

• data-bs-ride=“carousel”: （在主 .carousel 元素上）在页面加载时激活轮播并使其开始循环播放。
• data-bs-ride=“true”: （在主 .carousel 元素上，在 Bootstrap 5.2 中添加）类似于 data-bs-ride=“carousel”，如果启用了 JavaScript，则自动开始轮播。
• data-bs-target=“#myCarousel”: （在指示器和控件上）指向轮播的 ID。
• data-bs-slide-to=“0”: （在指示器上）导航到指定索引（从 0 开始）的幻灯片。
• data-bs-slide=“prev”: （在控件上）导航到上一张幻灯片。
• data-bs-slide=“next”: （在控件上）导航到下一张幻灯片。

data 属性的应用示例：

<!-- Carousel -->
<div id="myCarousel" class="carousel slide" data-bs-ride="carousel">
  <!-- Carousel Indicators -->
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="1" aria-label="Slide 2"></button>
  </div>
  <!-- Carousel Controls -->
  <button class="carousel-control-prev" type="button" data-bs-target="#myCarousel" 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="#myCarousel" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
  <!-- Carousel Inner (slides) would go here -->
</div>

通过 JavaScript

您也可以使用 JavaScript 手动初始化和控制轮播：

// Get the carousel element
var myCarouselElement = document.querySelector('#myCarousel');

// Initialize the carousel
var carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000, // Optional: set interval
  wrap: false     // Optional: prevent continuous cycling
});

// Example: Go to a specific slide (e.g., slide 1, which is index 1)
// carousel.to(1);

// Example: Go to previous slide
// carousel.prev();

// Example: Cycle items
// carousel.cycle();

// Example: Pause cycling
// carousel.pause();

轮播选项

选项可以通过 data 属性或 JavaScript 传递。对于 data 属性，将选项名称附加到 data-bs-，例如 data-bs-interval=""。

名称	类型	默认值	描述
interval	number | boolean	5000	自动循环播放项目之间的延迟时间。如果为 false，轮播将不会自动循环。
keyboard	boolean	true	轮播是否应该对键盘事件作出反应。
pause	string | boolean	”hover”	如果设置为 “hover”，则在 mouseenter 时暂停轮播的循环播放，在 mouseleave 时恢复。如果设置为 false，则悬停在轮播上不会暂停它。
ride	string | boolean	false	如果设置为 “carousel” 或 true，用户手动循环第一个项目后将自动播放轮播。如果设置为 false，则不会自动播放。
wrap	boolean	true	轮播是否应该连续循环或在最后一张幻灯片停止。
touch	boolean	true	轮播是否应该支持触摸屏设备上的左右滑动交互。

轮播方法

下表列出了所有可用的轮播方法，可以在轮播实例上调用（例如 myCarouselInstance.next()）。

方法	描述
.carousel(options) or new bootstrap.Carousel(element, options)	使用可选的 options 对象初始化轮播。
.cycle()	从左到右循环播放轮播项目。
.pause()	停止轮播循环播放项目。
.prev()	循环到上一项。
.next()	循环到下一项。
.nextWhenVisible()	仅在页面可见时循环到下一项（对性能很有用）。
.to(number)	将轮播循环到特定帧（从 0 开始，类似于数组）。
.dispose()	销毁元素的轮播。（移除事件监听器和 data 属性）。

轮播事件

Bootstrap 的轮播类暴露了几个用于挂钩轮播功能的事件。所有轮播事件都在轮播本身触发（即在 <div class=“carousel”> 上触发）。

事件类型	描述
slide.bs.carousel	当调用 slide 实例方法时，此事件会立即触发。
slid.bs.carousel	当轮播完成其滑动过渡时，此事件会触发。

使用事件的示例：

var myCarousel = document.getElementById('myCarousel');
myCarousel.addEventListener('slide.bs.carousel', function (event) {
  // event.direction: The direction in which the carousel is sliding (either "left" or "right").
  // event.relatedTarget: The DOM element that is being slid into place as the active item.
  // event.from: The index of the current item.
  // event.to: The index of the next item.
  console.log('Carousel is about to slide from ' + event.from + ' to ' + event.to);
});

幻灯片标题

在每个 <div class=“carousel-item”> 内添加 <div class=“carousel-caption”> 以创建每张幻灯片的标题。可以使用 .d-none .d-md-block 等显示辅助类在较小视口上隐藏标题。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Bootstrap Carousel with Captions</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
  <style>
    .carousel-item img {
      max-height: 400px; /* Example height, adjust as needed */
      object-fit: cover;
      width: 100%;
    }
  </style>
</head>
<body>

<div id="myCarousel" class="carousel slide" data-bs-ride="carousel">
  <!-- Indicators -->
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>

  <!-- Wrapper for slides -->
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="docs/english/books/bootstrap/images/cinqueterre.jpg" class="d-block w-100" alt="Chania">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label (Chania)</h5>
        <p>The atmosphere in Chania has a touch of Florence and Venice.</p>
      </div>
    </div>

    <div class="carousel-item">
      <img src="docs/english/books/bootstrap/images/img_chania2.jpg" class="d-block w-100" alt="Another view of Chania">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label (Chania)</h5>
        <p>Exploring the beautiful streets and architecture.</p>
      </div>
    </div>

    <div class="carousel-item">
      <img src="docs/english/books/bootstrap/images/img_flower.jpg" class="d-block w-100" alt="Flower">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label (Flowers)</h5>
        <p>Beautiful flowers in Kolymbari, Crete.</p>
      </div>
    </div>
  </div>

  <!-- Left and right controls -->
  <button class="carousel-control-prev" type="button" data-bs-target="#myCarousel" 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="#myCarousel" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>