本文详解如何使用 bootstrap 5 原生 api 和轻量级 javascript，让轮播图在页面加载时自动播放，并在遍历完所有幻灯片后精准暂停，避免无限循环。
在 Bootstrap 5 中，data-bs-ride="carousel" 可启用页面加载时自动播放，但默认会无限循环（loop），无法满足“仅播放一轮即暂停”的业务需求（如产品功能引导页、单次展示型 Banner）。官方未提供原生 pauseOnEnd 配置，需结合事件监听与状态判断手动实现。
✅ 正确实现逻辑
核心思路是：
- 启用自动播放（data-bs-ride="carousel" 或 JS 初始化时设 interval: 5000）；
- 监听 slid.bs.carousel 事件（每次幻灯片切换完成时触发）；
- 在回调中获取当前活跃项索引（event.to）和总幻灯片数；
- 当 event.to === totalSlides - 1（即到达最后一张）时，调用 .carousel('pause')。
⚠️ 注意：不要使用 slide.bs.carousel（切换开始前触发），否则可能因异步导致判断失效；也不要监听 slid.bs.carousel 后立即暂停——需确保是最后一次切换完成。
✅ 完整可运行代码示例
<!-- HTML 结构（保持原样，仅移除 data-bs-ride="carousel" 避免冲突） --> <div id="home-carousel" class="carousel slide"> <!-- indicators & inner items... --> </div>
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 在用户点击控件时为对应 <button> 元素；在自动播放时为 null，可据此区分触发源。
? 总结
- ❌ 错误做法：$('#home-carousel').on('slid.bs.carousel', () => $(...).carousel('pause')) —— 会在每张切换后都暂停，首张播完即停。
- ✅ 正确做法：监听 slid.bs.carousel，结合 wrap: false + 索引比对，精准定位最后一张并暂停。
- ? Bootstrap 5.2+ 支持 data-bs-config JSON 配置，但 wrap 和 interval 等关键参数仍推荐 JS 初始化，更可控、易调试。
通过以上方案，即可优雅实现「一次播完、自动收工」的轮播体验，兼顾语义化、可维护性与跨设备兼容性。
