本文介绍在 React 项目中构建一个水平滚动横幅的完整方案：既通过 CSS @keyframes 实现流畅自动滚动，又支持鼠标滚轮/触摸拖拽的双向手动控制，避免因 transform 动画导致内容不可逆丢失的问题。
本文介绍在 react 项目中构建一个水平滚动横幅的完整方案：既通过 css `@keyframes` 实现流畅自动滚动，又支持鼠标滚轮/触摸拖拽的双向手动控制，避免因 `transform` 动画导致内容不可逆丢失的问题。
要实现「自动滚动 + 手动双向滚动」共存的横幅（marquee），关键在于分离动画控制逻辑与 DOM 滚动状态——不能让 CSS transform: translateX() 动画与 scrollLeft 手动操作相互干扰。原问题中手动滚动仅向右生效、左侧内容无法回显，正是因为 translateX(-100%) 将元素整体位移后，scrollLeft 作用于已偏移的视觉容器，造成坐标系错位。
✅ 正确解法是：统一使用 scrollLeft 驱动滚动，将自动滚动也交由 JavaScript 控制（配合 requestAnimationFrame），从而与手动滚轮事件共享同一状态源，确保双向可逆、无缝衔接。
✅ 推荐实现：纯 scrollLeft 驱动 + 状态同步
以下是一个生产就绪的 React Hook 方案，支持：
- 鼠标悬停暂停自动滚动
- 滚轮/触摸拖拽自由左右滚动
- 自动恢复滚动（离开区域后）
- 无内存泄漏（正确清理定时器与事件监听）
import { useRef, useState, useEffect, useLayoutEffect } from 'react';
const HorizontalMarquee = ({ children }: { children: React.ReactNode }) => {
const containerRef = useRef<HTMLDivElement>(null);
const [isPaused, setIsPaused] = useState(false);
const [scrollPos, setScrollPos] = useState(0);
const animationRef = useRef<number>(0);
const scrollSpeed = 0.5; // px/frame，可调
// 启动自动滚动动画循环
const startAutoScroll = () => {
if (!containerRef.current) return;
const container = containerRef.current;
const { scrollWidth, clientWidth } = container;
const animate = () => {
if (isPaused || scrollWidth <= clientWidth) return;
setScrollPos(prev => {
let next = prev + scrollSpeed;
// 循环滚动：到达末尾时跳回起点（可选）
if (next >= scrollWidth - clientWidth) {
next = 0;
}
container.scrollLeft = next;
return next;
});
animationRef.current = requestAnimationFrame(animate);
};
animationRef.current = requestAnimationFrame(animate);
};
// 清理动画
useEffect(() => {
return () => cancelAnimationFrame(animationRef.current);
}, []);
// 悬停控制
const handleMouseEnter = () => setIsPaused(true);
const handleMouseLeave = () => setIsPaused(false);
// 手动滚动（兼容滚轮 & 触摸）
const handleWheel = (e: WheelEvent) => {
e.preventDefault();
if (!containerRef.current) return;
const { scrollLeft } = containerRef.current;
containerRef.current.scrollLeft = scrollLeft + e.deltaY;
};
// 初始化 & 响应 isPaused 变化
useLayoutEffect(() => {
if (!isPaused) {
startAutoScroll();
} else {
cancelAnimationFrame(animationRef.current);
}
}, [isPaused]);
return (
<div
ref={containerRef}
className="marquee-container"
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
onWheel={handleWheel}
style={{ overflowX: 'auto', scrollBehavior: 'smooth' }}
>
<div className="marquee-content">
{children}
</div>
</div>
);
};
export default HorizontalMarquee;? 对应 CSS（精简可靠）
.marquee-container {
display: flex;
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;
}⚠️ 注意事项与最佳实践
- 避免混合 transform 与 scrollLeft：CSS 动画位移会破坏原生滚动上下文，导致 scrollLeft 失效或行为异常。始终选择其一作为唯一滚动源。
- 使用 useLayoutEffect 启停动画：确保 DOM 更新后立即响应，避免视觉跳变。
- scroll-behavior: smooth 提升体验：但注意它可能与高频 scrollLeft 更新冲突；若出现卡顿，可改用 scrollTo({ left: pos, behavior: 'auto' }) 或移除此样式。
- 循环滚动增强：如需无缝循环，可在 scrollWidth - clientWidth 处重置 scrollLeft 为 0（示例中已预留逻辑），或采用双倍内容拼接（适用于静态内容）。
- 移动端适配：添加 touchstart/touchmove 事件监听，结合 preventDefault() 实现触摸拖拽（本例未展开，但原理一致）。
该方案兼顾性能、可维护性与用户体验，彻底规避了 transform 与 scrollLeft 混用引发的状态不一致问题，是现代 React 项目中实现专业级横幅滚动的推荐路径。
