Swiper禁用垂直滚动仅允许水平滑动的实现方法

在 Swiper 中，通过启用 mousewheel.forceToAxis: true 并配合 touch-action: pan-x CSS 样式，即可精准限制用户仅能通过水平滚动切换幻灯片，有效避免垂直滚动意外触发翻页，整体滚动体验显著提升。

实际开发中，使用 Swiper 构建横向轮播时最令人头疼的场景是什么？就是用户原本想上下滚动页面，但手指刚划过轮播区域，幻灯片就跟着切换了——交互体验瞬间变得糟糕。Swiper 默认的鼠标滚轮会响应任意方向的滚动事件，当垂直滚动经过 Swiper 时同样会触发翻页，这显然不符合我们的预期。

要实现“仅水平滚动切换页面、垂直滚动穿透给外层页面”的行为（类似 macOS 那种丝滑的惯性滚动效果），需要从 JavaScript 和 CSS 两个层面协同配置。

核心解决思路
关键在于开启 mousewheel.forceToAxis: true —— 这是 Swiper v10+ 版本引入的配置项，它让 Swiper 仅在检测到明确的水平滚动（deltaX 绝对值显著大于 deltaY）时才触发翻页，垂直滚动则直接忽略，交由父容器或页面自身处理。

const swiper = new Swiper('.my-swiper', {  direction: 'horizontal',  slidesPerView: 'auto',  spaceBetween: 16,  mousewheel: {    forceToAxis: true, // ✅ 关键：仅响应水平滚动轴    invert: false,      // 可选：是否反转滚动方向    releaseOnEdges: false // 可选：到达边界时是否释放滚动给页面  },  // 其他配置...});

仅有 JS 配置还不够，移动端的触摸滚动同样会造成干扰。需要在 CSS 中为 Swiper 容器显式声明 touch-action: pan-x，告知浏览器“此处只允许水平拖拽，垂直方向保持不动”：

.my-swiper {  touch-action: pan-x; /* 允许水平拖拽，禁用垂直拖拽 */}/* 可选：增强兼容性，防止子元素干扰 */.my-swiper .swiper-wrapper,.my-swiper .swiper-slide {  touch-action: pan-x;}

注意事项与最佳实践

• forceToAxis: true 完全依赖 Swiper 内部对 deltaX / deltaY 的阈值判断，无需额外编写计算逻辑；
• 若希望在滚动到首尾幻灯片时将垂直滚动“释放”给页面，可以启用 mousewheel.releaseOnEdges: true；
• 注意避免同时设置 mousewheel: true（对象简写）和 mousewheel: { forceToAxis: true }，后者会覆盖前者；
• 在 SSR 或动态初始化场景下，请确保 DOM 就绪后再创建 Swiper 实例，并验证 swiper.params.mousewheel?.forceToAxis === true；
• 测试时务必覆盖桌面（鼠标滚轮）、平板（触控拖拽）和手机（手指滑动）三种设备场景，缺一不可。

通过上述组合配置，Swiper 即可严格遵循“水平滚动切换页面、垂直滚动穿透给页面”的交互逻辑——横向浏览足够流畅，页面的整体纵向滚动也不会受到破坏。