自动手动滚动横幅动画实现技巧

本文深入解析了在 React 中实现专业级水平横幅滚动的完整方案——摒弃易导致状态错乱的 CSS transform 动画，转而统一采用 scrollLeft 驱动自动与手动双向滚动，通过 requestAnimationFrame 精确控制动画帧、useLayoutEffect 同步生命周期、事件监听兼容鼠标滚轮与触摸拖拽，并支持悬停暂停、无缝循环及内存安全清理，真正解决内容丢失、方向受限、体验割裂等常见痛点，为开发者提供一套高性能、高可靠性且开箱即用的生产就绪实践。

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

今天关于《自动手动滚动横幅动画实现技巧》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！