本文介绍在 react 中结合 css 动画与手动控制，构建支持自动滚动、悬停暂停、双向鼠标滚轮 / 拖拽滚动的响应式水平横幅（marquee），解决 translatex 动画与 scrollleft 冲突导致内容不可逆丢失的问题。
本文介绍在 react 中结合 css 动画与手动控制，构建支持自动滚动、悬停暂停、双向鼠标滚轮 / 拖拽滚动的响应式水平横幅（marquee），解决 translatex 动画与 scrollleft 冲突导致内容不可逆丢失的问题。
在现代 Web 开发中，水平滚动横幅（如产品轮播、新闻跑马灯、标签流）常需兼顾 自动播放的流畅性 与用户交互的可控性。但若直接混合 CSS @keyframes 平移动画（如 transform: translateX()）与 DOM 原生滚动（如 scrollLeft），极易引发状态冲突：动画持续修改元素视觉位置，而 scrollLeft 操作无法同步更新动画进度，导致手动向左滚动时内容“消失”且无法回溯——本质是两种位移机制（CSS 变换 vs. 滚动容器偏移）未对齐。
✅ 推荐方案：分离关注点 —— CSS 负责自动动画，JS 负责滚动容器控制
最佳实践是 放弃在动画元素上混用 transform 和 scrollLeft，转而统一使用 scrollLeft 作为唯一位置控制源。CSS 动画仅用于 纯视觉自动滚动，而交互操作（悬停、滚轮、触摸拖拽）则通过 JS 精确驱动容器的 scrollLeft，并动态启停动画。
? 核心实现步骤
-
HTML 结构：使用标准滚动容器
const Banner = ({items}: {items: string[] }) => {const containerRef = useRef<HTMLDivElement>(null); const [isAutoScroll, setIsAutoScroll] = useState(true); const [isDragging, setIsDragging] = useState(false); const dragStartX = useRef(0); const scrollStartLeft = useRef(0); // 自动滚动逻辑（useEffect + requestAnimationFrame）useEffect(() => { if (!isAutoScroll || !containerRef.current) return; const container = containerRef.current; const scrollWidth = container.scrollWidth - container.clientWidth; let startTime: number | null = null; const animate = (timestamp: number) => {if (!startTime) startTime = timestamp; const elapsed = timestamp - startTime; // 每 8s 完成一次完整滚动（可调）const progress = (elapsed % 8000) / 8000; container.scrollLeft = progress * scrollWidth; if (isAutoScroll) requestAnimationFrame(animate); }; const id = requestAnimationFrame(animate); return () => cancelAnimationFrame(id); }, [isAutoScroll]); // 悬停暂停 / 恢复 const handleMouseEnter = () => setIsAutoScroll(false); const handleMouseLeave = () => setIsAutoScroll(true); // 滚轮控制（双向）const handleWheel = (e: WheelEvent) => {e.preventDefault(); if (containerRef.current) {containerRef.current.scrollLeft += e.deltaY > 0 ? 30 : -30;} }; // 拖拽控制（增强体验）const handleMouseDown = (e: React.MouseEvent) => {if (!containerRef.current) return; setIsDragging(true); dragStartX.current = e.clientX; scrollStartLeft.current = containerRef.current.scrollLeft; containerRef.current.style.cursor = 'grabbing'; containerRef.current.style.userSelect = 'none'; }; const handleMouseMove = (e: MouseEvent) => {if (!isDragging || !containerRef.current) return; const deltaX = e.clientX - dragStartX.current; containerRef.current.scrollLeft = scrollStartLeft.current - deltaX; }; const handleMouseUp = () => { setIsDragging(false); if (containerRef.current) {containerRef.current.style.cursor = 'grab'; containerRef.current.style.userSelect = 'auto';} }; // 绑定全局事件（注意 cleanup）useEffect(() => { if (isDragging) {document.addEventListener('mousemove', handleMouseMove); document.addEventListener('mouseup', handleMouseUp); return () => { document.removeEventListener('mousemove', handleMouseMove); document.removeEventListener('mouseup', handleMouseUp); }; } }, [isDragging]); return (<div ref={containerRef} className="banner-container" onMouseEnter={handleMouseEnter} onMouseLeave={handleMouseLeave} onWheel={handleWheel} onMouseDown={handleMouseDown} > <div className="banner-content"> {items.map((item, i) => (<div key={i} className="banner-item">{item}</div> ))} {/* 复制首项至末尾，实现无缝循环（可选）*/} {items.length > 0 && ( <div className="banner-item">{items[0]}</div> )} </div> </div> ); }; -
CSS 样式：专注滚动容器与内容布局
立即学习 “ 前端免费学习笔记（深入）”；
.banner-container {overflow-x: auto; overflow-y: hidden; scroll-behavior: smooth; /* 启用平滑滚动 */ scrollbar-width: none; /* Firefox 隐藏滚动条 */ -ms-overflow-style: none; /* IE/Edge */} .banner-container::-webkit-scrollbar {display: none; /* Chrome/Safari */} .banner-content {display: flex; gap: 1rem; padding: 0.5rem 0; /* 可选：无缝循环需确保总宽度足够 */ min-width: max-content;} .banner-item {flex: 0 0 auto; white-space: nowrap; padding: 0.75rem 1.5rem; background: #f0f9ff; border-radius: 6px; font-size: 0.9rem;}
⚠️ 关键注意事项
- 避免 transform 与 scrollLeft 混用：二者属于不同渲染管线，强行共存会导致布局错乱和不可预测的偏移。
- 无缝循环技巧：若需无限滚动效果，可在 .banner-content 末尾重复添加首项（如示例），并确保 scrollWidth 计算包含冗余内容；或使用 CSS scroll-snap + 动态克隆节点。
- 性能优化：
- 使用 requestAnimationFrame 替代 setInterval 控制自动滚动；
- 拖拽时监听 document 而非容器，防止鼠标快速移出失焦；
- 添加 will-change: scroll-position（谨慎使用）提示浏览器优化。
- 无障碍支持：为 .banner-container 添加 aria-live=”polite” 和 role=”region”，并在自动播放时提供显式暂停按钮（符合 WCAG 2.2）。
? 总结
真正健壮的交互式横幅，不依赖 CSS 动画“模拟”滚动，而是以原生 scrollLeft 为单一事实源，由 JavaScript 统一协调自动与手动行为。这种方式彻底规避了变换坐标系冲突，支持精准双向滚动、拖拽、键盘导航（可扩展 Tab + ArrowLeft/Right），并具备良好的可维护性与可访问性。对于复杂交互动效（如弹性回弹、惯性滑动），可进一步集成 Framer Motion 或 React Spring，但核心原则不变：滚动状态必须集中管理，不可分散于 CSS 与 JS 之间。
