Bootstrap Carousel动态多图轮播滚动失效问题修复

核心故障原因 #

故障由两个问题共同导致，其中模板渲染问题是滚动完全失效的直接诱因：

1. 模板渲染类名错误：PHP循环生成轮播项时，给所有.carousel-item节点都加了active类。Bootstrap轮播组件强制要求同一时间仅能有1个轮播项带有active类标记为当前激活项，多个激活项会导致组件初始化时索引计算完全错乱，切换事件无法正常触发。
2. JS逻辑硬编码+逻辑错误：
   • 写死itemsPerSlide = 5，和现有响应式布局规则不匹配（lg屏一行显示4张、md屏3张、sm屏2张、移动端1张），边界判断完全失效
   • 右滑回退时的节点循环逻辑错误，固定取第0个节点追加，会导致轮播项顺序错乱

修复步骤 #

1. 修正PHP模板渲染逻辑 #

仅给第一个轮播项添加active类，其余项不添加该类名，替换原有轮播项循环代码：

<!-- slides -->
<div class="carousel-inner row w-100 mx-auto" role="listbox">
  <?php 
  if(sizeof($cartoons_category_data) > 0){
    for($i = 0; $i< count($cartoons_category_data) ; $i++){ 
      $active = $i === 0 ? 'active' : '';
  ?>
  <div class="carousel-item col-12 col-sm-6 col-md-4 col-lg-3 <?php echo $active; ?>">
    <img src="<?php echo base_url('assets/uploads/library/'.$cartoons_category_data[$i]); ?>" class="img-fluid mx-auto d-block" alt="cartoon-<?php echo $i; ?>">
  </div>
  <?php 
    }
  } ?>
</div>

2. 替换原有轮播JS逻辑 #

移除硬编码的每屏显示数量，根据响应式断点动态计算，修正右滑时的节点移动逻辑，新增窗口resize时的重置逻辑：

/*
    Carousel 滚动逻辑
*/
// 按当前响应式断点计算每屏展示的素材数量
function getPerSlideCount() {
  const width = $(window).width();
  if (width >= 992) return 4;
  if (width >= 768) return 3;
  if (width >= 576) return 2;
  return 1;
}

$('#carousel-example').on('slide.bs.carousel', function(e) {
  const $target = $(e.relatedTarget);
  const currentIdx = $target.index();
  const perSlide = getPerSlideCount();
  const total = $('.carousel-item').length;

  // 到达轮播末尾时循环补充节点，实现无限滚动
  if (currentIdx >= total - (perSlide - 1)) {
    const needAppend = perSlide - (total - currentIdx);
    for (let i = 0; i < needAppend; i++) {
      if (e.direction === "left") {
        // 向后滚动时，把头部的节点移到末尾
        $('.carousel-item').eq(i).appendTo('.carousel-inner');
      } else {
        // 向前滚动时，把尾部的节点移到头部，修复原逻辑固定取第0项的错误
        $('.carousel-item').eq(total - 1 - i).prependTo('.carousel-inner');
      }
    }
  }
});

// 窗口大小变化时回到轮播开头，避免响应式切换后布局错位
$(window).on('resize', () => {
  $('#carousel-example').carousel(0);
});

验证标准 #

• 页面渲染完成后，DOM中仅存在1个带active类的.carousel-item节点
• 点击前后切换按钮，轮播可平滑滚动，无卡滞、跳项、顺序错乱问题
• 切换不同屏幕尺寸（模拟移动端、平板、桌面端），滚动逻辑正常
• 上传任意数量（25-30张区间）的新素材后，轮播可正常循环展示所有内容

内容的提问来源于stack exchange，提问作者Amrita