使用ScrollTrigger实现水平滚动时容器宽度异常问题求助

根因说明 #

出现该问题的核心是水平滚动总距离计算偏差，ScrollTrigger默认的滚动终止位置配置没有扣除容器自身的可视宽度，导致实际滚动距离比需要的总偏移量少了一个视口宽度，既无法展示最后一项元素，也会导致激活判定的进度计算错位。

修复步骤 #

• 修正滚动终止位置计算
  原有配置通常直接取容器scrollWidth作为滚动总距离，需要改为扣除容器可视宽度clientWidth的值：end: () => "+=" + (container.scrollWidth - container.clientWidth)，该值才是水平方向需要滚动的真实总距离。
• 修正水平滚动属性配置
  显式给ScrollTrigger传入horizontal: true参数，告知插件当前为水平滚动场景，自动对齐元素判定的坐标轴逻辑。
• 修正位移动画目标值
  如果用GSAP的位移动画实现水平滚动，动画的x偏移值同样要对应调整，避免动画进度和滚动进度不匹配：x: () => -(container.scrollWidth - container.clientWidth)
• 修正元素激活判定逻辑
  基于修正后的滚动进度计算激活索引，避免因滚动距离不足导致的索引判定偏移。

核心代码示例 #

const scrollContainer = document.querySelector('.horizontal-scroll-container')
const itemList = gsap.utils.toArray('.scroll-item')

gsap.to(itemList, {
  xPercent: -100 * (itemList.length - 1),
  ease: 'none',
  scrollTrigger: {
    trigger: scrollContainer,
    pin: true,
    scrub: 0.5,
    // 修正滚动终止位置
    end: () => "+=" + (scrollContainer.scrollWidth - scrollContainer.clientWidth),
    // 显式声明水平滚动
    horizontal: true,
    onUpdate: (instance) => {
      // 基于修正后的进度计算准确的激活索引
      const activeIdx = Math.round(instance.progress * (itemList.length - 1))
      itemList.forEach((item, idx) => item.classList.toggle('active', idx === activeIdx))
    }
  }
})

注意事项 #

如果你使用flex/grid布局排列子元素，需要确认子元素的外边距、边框是否被正确纳入scrollWidth计算，部分浏览器下子元素溢出的外边距不会被计入容器总宽度，需要手动把对应宽度补充到滚动总距离的计算中，避免出现1-2px的滚动偏差。

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