如何禁用 Swiper 的垂直滚动并仅允许水平滑动

在 Swiper 中，可通过配置 mousewheel.forceToAxis: true 结合 touch-action: pan-x CSS 规则，精准限制用户仅能通过水平滚动切换幻灯片，避免垂直滚动意外触发翻页，提升页面整体滚动体验。

在 swiper 中，可通过配置 `mousewheel.forcetoaxis: true` 结合 `touch-action: pan-x` css 规则，精准限制用户仅能通过水平滚动切换幻灯片，避免垂直滚动意外触发翻页，提升页面整体滚动体验。

Swiper 默认启用鼠标滚轮（mousewheel）时会响应任意方向的滚动事件，导致用户在页面上垂直滚动经过 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 // 可选：到达边界时是否释放滚动给页面  },  // 其他配置...});

⚠️ 重要补充：CSS 层面必须配合设置
仅靠 JS 配置还不够。为防止移动端触摸滚动干扰，需为 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 或动态初始化场景中，确保 Swiper 实例在 DOM 就绪后创建，并验证 swiper.params.mousewheel?.forceToAxis === true；
• 测试务必覆盖桌面（鼠标滚轮）、平板（触控拖拽）及手机（手指滑动）三端行为。

通过上述组合配置，Swiper 将严格遵循“水平滚动切页、垂直滚动穿透”的交互逻辑，既保留横向浏览的流畅性，又不破坏页面整体的纵向滚动体验。