实现 React 中卡片容器的自动水平滚动动画（CSS 驱动方案）

本文介绍一种基于 css @keyframes 与 transform: translateX() 的纯声明式自动水平滚动方案，无需手动管理帧循环或状态，兼容性好、性能高，适用于国家卡片等横向流式布局场景。

本文介绍一种基于 css `@keyframes` 与 `transform: translatex()` 的纯声明式自动水平滚动方案，无需手动管理帧循环或状态，兼容性好、性能高，适用于国家卡片等横向流式布局场景。

在 react 应用中实现无交互、自动持续的水平滚动效果（如轮播国家卡片），最健壮且可维护的方式并非依赖 requestanimationFrame 手动更新 transform 值，而是交由浏览器原生 CSS 动画引擎处理——它天然支持硬件加速、时间线精确控制，并避免了 js 状态同步带来的抖动与边界误差问题。

以下是一个完整、生产就绪的实现方案，核心思路是：
✅ 将卡片容器设为 display: flex 并允许其自然撑宽（scrollWidth）；
✅ 用 ref 动态获取容器总宽度，并通过内联样式注入到 @keyframes 的终点位移中；
✅ 利用 calc(100vw) 起始位置 + calc(-100%) 终点位置，实现从视口右侧平滑滑入、完全滑出左侧的无缝循环动画；
✅ 通过 animation-play-state 控制启停，便于后续扩展暂停/重播逻辑。

✅ 完整代码实现

App.js（主容器组件）

import { useRef, useEffect, useState } from "react"; import Card from "./Card"; import "./styles.css";  const data = [   { Name: "China" },   { Name: "Japan" },   { Name: "Germany" },   { Name: "Brazil" },   { Name: "Canada" },   { Name: "Australia" },   { Name: "Nigeria" },   { Name: "Mexico" } ];  export default function App() {   const containerRef = useRef(null);   const [containerWidth, setContainerWidth] = useState("100%");   const [playState, setPlayState] = useState("paused");    // 动态计算容器总宽度（含所有卡片及 margin），并启动动画   useEffect(() => {     if (containerRef.current) {       const width = containerRef.current.scrollWidth;       setContainerWidth(`${width}px`);       setPlayState("running");     }   }, []);    return (     <div className="App">       <div         ref={containerRef}         className="card-container"         style={{           width: containerWidth,           animationPlayState: playState         }}       >         {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: 20px 0; }  .card {   width: 200px !important;   height: 200px;   background: #ffffff;   box-shadow: 0px 1px 4px 1px rgba(158, 151, 151, 0.25);   border-radius: 15px;   margin: 12px;   padding: 12px; }  /* 滚动容器：flex 布局 + 自定义动画 */ .card-container {   display: flex;   transform: translateX(calc(100vw)); /* 起始位置：完全在视口右侧 */   animation: scrollHorizontal 12s linear infinite;   animation-play-state: paused; /* 初始暂停，由 JS 启动 */ }  @keyframes scrollHorizontal {   from {     transform: translateX(calc(100vw));   }   to {     transform: translateX(calc(-100%)); /* 终点：向左移动自身总宽度 */   } }  /* 可选：鼠标悬停暂停动画（提升用户体验） */ .card-container:hover {   animation-play-state: paused; }

⚠️ 注意事项与优化建议

• 宽度动态性：scrollWidth 在首次渲染后才可读取，因此必须用 useEffect + ref 获取；若卡片内容异步加载（如图片），需监听 resize 或使用 ResizeObserver 进行二次校准。
• 无缝循环：当前方案依赖 to: translateX(-100%) —— 即容器自身宽度。确保 .card-container 的 width 样式与 scrollWidth 严格一致，否则会出现“卡顿”或“跳帧”。本例中通过内联 style.width 强制同步。
• 性能保障：transform 和 opacity 是仅有的两个能触发 GPU 加速的 CSS 属性，本方案全程只操作 transform，无布局重排（reflow），60fps 稳定。
• 可扩展性：如需支持双向滚动、变速、或点击暂停/播放，只需扩展 playState 状态及对应事件处理器，CSS 动画本身无需修改。
• 响应式适配：若需适配移动端，建议将 100vw 替换为 100dvw（动态视口单位），并在小屏下降低 animation-duration 或禁用动画。

该方案已验证于 chrome/firefox/safari，无 polyfill 依赖，代码简洁、逻辑清晰、易于测试与维护，是 React 水平自动滚动场景的推荐实践。