实现 React 中卡片容器的自动水平滚动动画（CSS 驱动、高性能、可维护）

本文介绍一种基于 css @keyframes + transform: translateX() 的纯声明式方案，实现 react 中卡片列表的无缝、自动、无限水平滚动，避免 js 动画性能开销，支持响应式与动态内容。

本文介绍一种基于 CSS `@keyframes` + `transform: translateX()` 的纯声明式方案，实现 React 中卡片列表的无缝、自动、无限水平滚动，避免 JS 动画性能开销，支持响应式与动态内容。

在构建信息流式 ui（如国家/品牌轮播墙、标签云、推荐卡片栏）时，自动水平滚动是一种常见且高吸引力的交互形式。相比手动触发或依赖第三方库，一个轻量、可复用、性能友好的原生方案更具长期价值。本文推荐并详解一种以 CSS 动画为核心、React 仅负责状态协调的最佳实践——它规避了 requestanimationFrame 手动管理位移、边界重置及帧率不稳定等常见问题，同时保持完全可控与可扩展性。

✅ 核心思路：CSS 驱动 + 容器宽度自适应

动画逻辑完全交由 CSS @keyframes 处理，React 层只需：

• 获取容器真实总宽度（scrollWidth）；
• 动态设置 animation-play-state 启动动画；
• 通过 calc(100vw) 和 calc(-100%) 实现从视口右侧入场、滑出左侧的自然位移。

关键优势在于：
? 零 JS 动画计算 → 浏览器直接在合成层渲染，60fps 稳定；
? 无限循环无缝 → forwards infinite + 精确终点位移，无跳帧或回弹；
? 响应式友好 → 100vw 基于视口，-100% 基于容器自身宽度，天然适配缩放与 resize；
? 低耦合易复用 → 卡片组件（Card）完全无动画逻辑，专注展示。

? 完整实现代码

App.js —— 容器控制层

import { useRef, useEffect, useState } from "react"; import Card from "./Card"; import "./styles.css";  const data = [   { Name: "China" },   { Name: "USA" },   { Name: "Japan" },   { Name: "Germany" },   { Name: "Brazil" },   { Name: "Australia" },   { Name: "Nigeria" },   { Name: "Canada" } ];  export default function App() {   const containerRef = useRef(null);   const [containerWidth, setContainerWidth] = useState("100%");   const [isPlaying, setIsPlaying] = useState(false);    useEffect(() => {     if (!containerRef.current) return;      // 动态获取滚动总宽（含所有卡片+间距）     const width = containerRef.current.scrollWidth;     setContainerWidth(`${width}px`);     setIsPlaying(true); // 启动 CSS 动画   }, []);    return (     <div className="App">       <div         ref={containerRef}         className="cards-container"         style={{           width: containerWidth,           animationPlayState: isPlaying ? "running" : "paused"         }}       >         {data.map((item, idx) => (           <Card key={idx} cardName={item.Name} />         ))}       </div>     </div>   ); }

Card.js —— 纯展示组件（零动画逻辑）

export default function Card({ cardName }) {   return (     <div className="bubble">       <div className="card m-2 pt-2">         <div className="py-1">           <div className="fs-5 mt-2">{cardName}</div>         </div>       </div>     </div>   ); }

styles.css —— 样式与动画定义

.App {   overflow: hidden; /* 隐藏超出视口的内容 */   padding: 24px 0; }  .cards-container {   display: flex;   gap: 16px; /* 替代 margin，更可控 */   transform: translateX(calc(100vw)); /* 起始位置：完全在视口右侧 */   animation: scrollHorizontal 12s linear forwards infinite;   animation-play-state: paused; /* 初始暂停，由 JS 控制启动 */ }  @keyframes scrollHorizontal {   from {     transform: translateX(calc(100vw));   }   to {     transform: translateX(calc(-100%)); /* 终点：完全滑出左侧 */   } }  /* 卡片基础样式（bootstrap 兼容写法）*/ .card {   width: 200px;   height: 200px;   background: #ffffff;   box-shadow: 0 1px 4px 1px rgba(158, 151, 151, 0.25);   border-radius: 15px;   padding: 12px; }  .bubble {   flex-shrink: 0; /* 关键！禁止卡片被压缩 */ }

⚠️ 注意事项与优化建议

• flex-shrink: 0 不可省略：若卡片在 flex 容器中被压缩（如空间不足），会导致 scrollWidth 计算失真，动画错位。.bubble 类必须显式设置 flex-shrink: 0。
• 动画时长动态化：当前 12s 是固定值。如需根据卡片数量/宽度自适应速度，可在 useEffect 中计算：

  const duration = Math.max(8, data.length * 1.5); // 最小 8s，每卡约 1.5s // 然后传入 style={{ animationDuration: `${duration}s` }}

• 暂停/恢复控制：将 isPlaying 改为受控状态，即可轻松实现 hover 暂停、点击播放等交互：

  onMouseEnter={() => setIsPlaying(false)} onMouseLeave={() => setIsPlaying(true)}

• 无障碍考量：对动画敏感用户，建议添加 prefers-reduced-motion 检测：

  const prefersReducedMotion = window.matchMedia(   "(prefers-reduced-motion: reduce)" ).matches; useEffect(() => { if (prefersReducedMotion) setIsPlaying(false); }, []);

✅ 总结

该方案以「CSS 动画为引擎、React 为调度器」的设计哲学，兼顾性能、可维护性与扩展性。它不依赖任何第三方库，兼容主流 React 版本，并能无缝集成到现有 Bootstrap/Flexbox 布局体系中。当你需要一个轻量、稳定、专业级的自动水平滚动效果时，这是比 requestAnimationFrame 手动位移更现代、更可靠的选择。

立即学习“前端免费学习笔记（深入）”；