本文介绍在 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，它们提供更精细的控制力与时间轴管理。
通过以上实现，你将获得一个高性能、可访问、易维护的双向可控水平跑马灯组件——自动时丝滑流畅，手动时精准响应，且内容永不丢失。
