本文介绍在 react 项目中构建一个兼具自动水平滚动（css 动画）与用户悬停暂停、鼠标滚轮/触摸双向手动控制的 banner 跑马灯组件，解决 translatex 动画与 scrollleft 混用导致内容不可逆丢失的问题。
本文介绍在 react 项目中构建一个兼具自动水平滚动（css 动画）与用户悬停暂停、鼠标滚轮/触摸双向手动控制的 banner 跑马灯组件，解决 translatex 动画与 scrollleft 混用导致内容不可逆丢失的问题。
在现代 Web 开发中，水平跑马灯（marquee）常用于展示轮播 Banner、产品列表或通知流。理想体验应满足三点：自动循环播放、悬停时暂停动画、支持用户主动双向滚动（左/右）且不破坏内容连续性。但若直接混合使用 transform: translateX() CSS 动画与原生 scrollLeft 控制，会导致 dom 位移状态冲突——动画持续修改 transform，而 scrollLeft 修改的是滚动容器自身的滚动偏移，二者互不感知，最终造成“向右滚出的内容无法再向左滚回”的视觉断裂。
✅ 推荐方案：分离控制逻辑，用 animation-play-state 统一调度
核心思路是 避免同时操作 transform 和 scrollLeft。我们选择纯 CSS 动画驱动自动滚动，并通过 animation-play-state: paused/running 实现毫秒级暂停/恢复；手动交互则完全接管容器的 scrollLeft，此时自动动画已暂停，不会产生竞争。
1. React 组件实现（含状态管理与事件绑定）
import { useState, useRef, useEffect } from 'react'; const HorizontalMarquee = ({ items }: { items: string[] }) => { const containerRef = useRef<HTMLDivElement>(null); const [isAutoPlaying, setIsAutoPlaying] = useState(true); // 悬停控制：进入暂停，离开恢复 const handleMouseEnter = () => setIsAutoPlaying(false); const handleMouseLeave = () => setIsAutoPlaying(true); // 手动滚动：支持鼠标滚轮 & 触摸板（双向） const handleWheel = (e: React.WheelEvent) => { e.preventDefault(); if (!containerRef.current) return; const { current } = containerRef; // 向下滚动 → 向右滑动；向上滚动 → 向左滑动 current.scrollLeft += e.deltaY > 0 ? 30 : -30; }; // 可选：键盘方向键支持（增强可访问性） useEffect(() => { const handleKeyDown = (e: KeyboardEvent) => { if (!containerRef.current) return; const { current } = containerRef; if (e.key === 'ArrowRight') { current.scrollLeft += 50; } else if (e.key === 'ArrowLeft') { current.scrollLeft -= 50; } }; window.addEventListener('keydown', handleKeyDown); return () => window.removeEventListener('keydown', handleKeyDown); }, []); return ( <div className="marquee-container" ref={containerRef} onMouseEnter={handleMouseEnter} onMouseLeave={handleMouseLeave} onWheel={handleWheel} > {/* 复制内容以实现无缝循环（关键！） */} <div className="marquee-content"> {items.map((item, i) => ( <div key={`item-${i}`} className="marquee-item"> {item} </div> ))} {/* 再次渲染相同内容，形成视觉闭环 */} {items.map((item, i) => ( <div key={`clone-${i}`} className="marquee-item"> {item} </div> ))} </div> </div> ); }; export default HorizontalMarquee;2. CSS 样式（含无缝动画与响应式适配）
.marquee-container { overflow-x: auto; overflow-y: hidden; scroll-behavior: smooth; /* 隐藏滚动条（可选） */ scrollbar-width: none; /* Firefox */ } .marquee-container::-webkit-scrollbar { display: none; /* Chrome/Safari */ } .marquee-content { display: flex; gap: 1rem; animation: marquee 20s linear infinite; animation-play-state: running; } /* 暂停时禁用动画 */ .marquee-container:not(:hover) .marquee-content { animation-play-state: running; } .marquee-container:hover .marquee-content { animation-play-state: paused; } @keyframes marquee { 0% { transform: translateX(0); } 100% { transform: translateX(-50%); /* 注意：此处为 -50%，因内容已双倍渲染 */ } } .marquee-item { flex: 0 0 auto; min-width: 200px; /* 根据实际调整 */ height: 80px; background: #f0f9ff; border-radius: 8px; display: flex; align-items: center; justify-content: center; font-weight: 600; box-shadow: 0 2px 4px rgba(0,0,0,0.05); } /* 响应式：小屏减少间距、调整尺寸 */ @media (max-width: 768px) { .marquee-item { min-width: 140px; height: 60px; } .marquee-content { gap: 0.5rem; } }? 关键设计说明：
- 无缝循环原理：.marquee-content 中渲染两遍数据，CSS 动画 translateX(-50%) 刚好将第二组内容滑至可视区起点，视觉上无限连贯；
- 状态解耦：悬停仅控制 animation-play-state，手动滚动仅操作 scrollLeft，二者永不交叉；
- 无内存泄漏：事件监听器均在组件卸载时自动清理（useEffect 返回函数），onWheel 直接内联绑定更安全；
- 无障碍增强：补充键盘方向键支持，符合 WCAG 2.1 标准。
⚠️ 注意事项与进阶建议
- 不要混用 transform 与 scrollLeft：这是本问题的根本原因。一旦启用 transform 动画，就不要再对同一元素调用 scrollLeft，反之亦然。
- 性能优化：长列表建议用 React.memo 包裹 marquee-item，并结合 useCallback 缓存事件处理器。
- 移动端适配：如需支持触摸拖拽，可引入 useGesture（@use-gesture/react）监听 drag 事件，映射到 scrollLeft 更新。
- 替代方案（高阶需求）：若需帧同步动画（如跟随滚动速度变化）、物理缓动或复杂交互动画，推荐使用 Framer Motion 或 GSAP，它们提供更精细的控制力与时间轴管理。
通过以上实现，你将获得一个高性能、可访问、易维护的双向可控水平跑马灯组件——自动时丝滑流畅，手动时精准响应，且内容永不丢失。