本文详解如何使用 bootstrap 5 原生 api 和轻量级 javascript，让轮播图在页面加载时自动播放，并在遍历完所有幻灯片后精准暂停，避免无限循环。

在 Bootstrap 5 中，data-bs-ride=”carousel” 可启用页面加载时自动播放，但默认会无限循环（loop），无法满足“仅播放一轮即暂停”的业务需求（如产品功能引导页、单次展示型 Banner）。官方未提供原生 pauseOnEnd 配置，需结合事件监听与状态判断手动实现。

✅ 正确实现逻辑

核心思路是：

1. 启用自动播放（data-bs-ride=”carousel” 或 JS 初始化时设 interval: 5000）；
2. 监听 slid.bs.carousel 事件（每次幻灯片切换完成时触发）；
3. 在回调中获取当前活跃项索引（event.to）和总幻灯片数；
4. 当 event.to === totalSlides – 1（即到达最后一张）时，调用 .carousel(‘pause’)。

⚠️ 注意：不要使用 slide.bs.carousel（切换开始前触发），否则可能因异步导致判断失效；也不要监听 slid.bs.carousel 后立即暂停——需确保是最后一次切换完成。

✅ 完整可运行代码示例

document.addEventListener('DOMContentLoaded', function () {
  const carousel = document.getElementById('home-carousel');
  const carouselInstance = new bootstrap.Carousel(carousel, {
    interval: 5000,   // 自动播放间隔（ms）
    wrap: false       // 关键！禁用循环，到达末尾自动停止（不回跳到第一张）
  });

  // 监听每次切换完成
  carousel.addEventListener('slid.bs.carousel', function (e) {
    const slides = carousel.querySelectorAll('.carousel-item');
    const currentIndex = e.to;
    const totalSlides = slides.length;

    // 判断是否为最后一张（索引从 0 开始）
    if (currentIndex === totalSlides - 1) {
      carouselInstance.pause();
      console.log('✅ 已到达最后一张，轮播已暂停');
    }
  });
});

? 关键配置说明

选项	值	作用
wrap: false	false	必须设置。禁用循环模式，使轮播在最后一张后不再跳转至第一张，避免 slid.bs.carousel 多余触发。
interval	5000（或 null）	设为数字启用自动播放；设为 null 则仅手动触发，需配合 carousel(‘cycle’) 启动。
pause: ‘hover’	可选	鼠标悬停时暂停（不影响“播放一轮后暂停”逻辑）。

? 进阶技巧：兼容移动端 & 防误触

若需在用户手动操作（点击箭头/指示器）后仍保留“仅播一轮”逻辑，可增强判断：

carousel.addEventListener('slid.bs.carousel', function (e) {
  const slides = carousel.querySelectorAll('.carousel-item');
  const totalSlides = slides.length;

  // 仅当是自动播放触发的切换才检查暂停（排除用户手动切换）
  if (e.relatedTarget === null && e.to === totalSlides - 1) {
    carouselInstance.pause();
  }
});

✅ 提示：e.relatedTarget 在用户点击控件时为对应 元素；在自动播放时为 null，可据此区分触发源。

? 总结

• ❌ 错误做法：$(‘#home-carousel’).on(‘slid.bs.carousel’, () => $(…).carousel(‘pause’)) —— 会在每张切换后都暂停，首张播完即停。
• ✅ 正确做法：监听 slid.bs.carousel，结合 wrap: false + 索引比对，精准定位最后一张并暂停。
• ? Bootstrap 5.2+ 支持 data-bs-config JSON 配置，但 wrap 和 interval 等关键参数仍推荐 JS 初始化，更可控、易调试。

通过以上方案，即可优雅实现「一次播完、自动收工」的轮播体验，兼顾语义化、可维护性与跨设备兼容性。

https://www.php.cn/faq/2030607.html