本文介绍在 react 项目中构建一个兼具 css 自动水平滚动与用户交互式手动滚动（支持双向）的 banner 组件，通过状态驱动动画启停、scrollleft 精确控制及防冲突设计，解决 translatex 动画与原生滚动冲突导致内容不可逆消失的问题。
本文介绍在 react 项目中构建一个兼具 css 自动水平滚动与用户交互式手动滚动（支持双向）的 banner 组件，通过状态驱动动画启停、scrollleft 精确控制及防冲突设计，解决 translatex 动画与原生滚动冲突导致内容不可逆消失的问题。
要实现一个既可自动循环滚动、又支持用户悬停时双向手动拖拽/滚轮控制的水平 Banner（如产品展示栏），关键在于分离动画逻辑与滚动状态：不能让 CSS transform: translateX() 动画与 DOM 元素的 scrollLeft 属性共存并直接竞争——前者会覆盖后者，造成手动向左滚动后无法回溯已移出视口的内容。
✅ 推荐方案：CSS 动画 + 状态化启停 + 原生 scrollLeft 手动控制（无 transform 干扰）
核心思路是：仅在自动播放时启用 CSS 动画；一旦用户悬停或交互，立即暂停动画，并完全交由 scrollLeft 控制滚动位置。这样避免了 transform 和 scrollLeft 的样式冲突，确保手动滚动始终可逆、精准、响应自然。
1. React 组件结构（函数组件 + useState + useRef）
import { useState, useRef, useEffect } from 'react';
const HorizontalMarquee = ({ items }: { items: string[] }) => {
const containerRef = useRef<HTMLDivElement>(null);
const [isAutoPlaying, setIsAutoPlaying] = useState(true);
const autoScrollInterval = useRef<NodeJS.Timeout | null>(null);
// 启动/停止自动滚动定时器（替代 CSS animation，更可控）
useEffect(() => {
if (!isAutoPlaying || !containerRef.current) return;
const scrollStep = () => {
const el = containerRef.current!;
const scrollWidth = el.scrollWidth;
const clientWidth = el.clientWidth;
// 滚动至下一个“视口宽度”位置，支持无缝循环（需内容重复或 JS 补充逻辑）
el.scrollLeft = (el.scrollLeft + 1) % (scrollWidth - clientWidth);
};
autoScrollInterval.current = setInterval(scrollStep, 30); // ~33fps
return () => {
if (autoScrollInterval.current) {
clearInterval(autoScrollInterval.current);
}
};
}, [isAutoPlaying]);
// 鼠标悬停控制
const handleMouseEnter = () => setIsAutoPlaying(false);
const handleMouseLeave = () => setIsAutoPlaying(true);
// 手动滚轮控制（双向，平滑）
const handleWheel = (e: React.WheelEvent) => {
e.preventDefault();
if (!containerRef.current) return;
const { currentTarget } = e;
currentTarget.scrollLeft += e.deltaY > 0 ? 20 : -20;
};
return (
<div
ref={containerRef}
className="marquee-container"
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
onWheel={handleWheel}
>
{/* 内容区域：建议使用 flex + white-space: nowrap 或 inline-flex */}
<div className="marquee-content">
{items.map((item, i) => (
<div key={i} className="marquee-item">
<img src={item} alt={`item-${i}`} />
</div>
))}
{/* 可选：追加副本实现视觉无缝循环 */}
{items.map((item, i) => (
<div key={`dup-${i}`} className="marquee-item">
<img src={item} alt={`dup-${i}`} />
</div>
))}
</div>
</div>
);
};
export default HorizontalMarquee;2. 对应 CSS（简洁、无 transform 干扰）
.marquee-container {
overflow-x: auto;
scroll-behavior: smooth; /* 可选：提升手动滚动体验 */
scrollbar-width: none; /* Firefox 隐藏滚动条 */
}
.marquee-container::-webkit-scrollbar {
display: none; /* Chrome/Safari 隐藏滚动条 */
}
.marquee-content {
display: flex;
gap: 1rem;
padding: 0 1rem;
}
.marquee-item {
flex: 0 0 auto; /* 防止缩放，保持原始尺寸 */
width: 200px; /* 示例固定宽，按需调整 */
height: 120px;
}
/* 可选：添加轻微弹性阻尼（移动端友好） */
.marquee-container {
overscroll-behavior-x: contain;
}⚠️ 注意事项与最佳实践
- 不要混用 transform 与 scrollLeft：CSS translateX 是渲染层位移，不改变 scrollLeft 值，会导致手动滚动“失焦”。务必选择其一作为唯一滚动机制。
- 无缝循环建议：若需无限滚动效果，推荐在 JS 中动态计算 scrollLeft 并配合内容复制（如上例双份 item），或使用 scrollIntoView() + 虚拟列表库（如 react-window）。
- 性能优化：对长列表，使用 useCallback 包裹 handleWheel；避免在 onWheel 中频繁读写 scrollLeft（本例已足够轻量）。
- 无障碍支持：为 .marquee-container 添加 aria-live="polite" 和 role="region"，并在自动播放时提供暂停按钮（符合 WCAG 2.1 SC 2.2.2）。
- 移动端适配：补充 touchstart/touchmove 事件处理，或直接使用 @use-gesture/react 库统一手势逻辑。
✅ 总结
真正健壮的水平滚动 Banner 不依赖“CSS 动画 + 手动事件强行覆盖”的脆弱组合，而应以 scrollLeft 为唯一事实源（source of truth），通过 React 状态协调自动与手动模式切换。本文方案兼顾可维护性、可访问性与跨端一致性，适用于中大型 React 项目，且易于扩展为支持触摸拖拽、键盘导航或播放速率调节等高级功能。
