本文介绍如何在 react 中无需用户交互即可实现容器内卡片元素的自动、循环、平滑水平滚动，重点对比 js 动画与 CSS 动画方案，推荐基于 scrollWidth + @keyframes 的高性能 CSS 驱动方案，并提供可复用的代码结构与关键注意事项。
本文介绍如何在 react 中无需用户交互即可实现容器内卡片元素的自动、循环、平滑水平滚动，重点对比 js 动画与 css 动画方案，推荐基于 `scrollwidth` + `@keyframes` 的高性能 css 驱动方案，并提供可复用的代码结构与关键注意事项。
在构建信息流、国家/品牌轮播、产品展示等横向内容区域时，自动水平滚动（auto Horizontal Scroll）是一种常见且高吸引力的交互模式。相比依赖 requestanimationFrame 手动更新 transform 的 JavaScript 方案，现代 React 应用更推荐纯 CSS 驱动的动画方案——它性能更高（GPU 加速）、代码更简洁、兼容性更好，且天然支持暂停/恢复、速率控制等能力。
以下是一个生产就绪的实现方案，分为三部分：容器动态宽度计算、CSS 关键帧定义、以及响应式动画控制。
✅ 核心实现逻辑
- 动态获取容器总宽度：使用 useRef 获取 dom 节点，通过 scrollWidth 精确获取所有子元素（卡片）水平排列后的总宽度（含 margin/padding），避免硬编码导致的偏移错位；
- CSS 动画精准位移：利用 translateX(calc(100vw)) 作为起点（确保首张卡片从视口右侧入场），终点设为 translateX(calc(-100%))（即向左移动整个容器自身宽度），实现无缝循环；
- 动画状态可控：通过 animation-play-state 动态控制播放/暂停，便于后续扩展（如 hover 暂停、点击切换等）。
? 完整代码示例
App.js
import { useRef, useEffect, useState } from "react"; import Card from "./Card"; import "./styles.css"; const data = [ { Name: "China" }, { Name: "United States" }, { 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 [playState, setPlayState] = useState("paused"); // 初始化：测量真实滚动宽度并启动动画 useEffect(() => { if (containerRef.current) { const width = containerRef.current.scrollWidth; setContainerWidth(`${width}px`); setPlayState("running"); // 启动自动滚动 } }, []); return ( <div className="App"> <div ref={containerRef} className="scroll-container" style={{ width: containerWidth, animationPlayState: playState }} > {data.map((item, index) => ( <Card key={index} 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: 0 1px 4px 1px rgba(158, 151, 151, 0.25); border-radius: 15px; margin: 12px; padding: 12px; } /* 滚动容器：Flex 布局 + 动画核心 */ .scroll-container { display: flex; gap: 12px; /* 替代 margin，更可控 */ transform: translateX(calc(100vw)); animation: scrollHorizontal 12s linear infinite; animation-play-state: paused; } /* 关键帧：从右到左，覆盖完整内容宽度 */ @keyframes scrollHorizontal { from { transform: translateX(calc(100vw)); } to { transform: translateX(calc(-100%)); } } /* 可选：鼠标悬停暂停（提升用户体验）*/ .scroll-container:hover { animation-play-state: paused; }⚠️ 注意事项与最佳实践
- 避免 margin 累计误差：建议用 CSS gap 替代子元素 margin 控制间距，防止 scrollWidth 计算偏差；
- 响应式兼容性：若需适配移动端，可在媒体查询中调整 animation-duration 或 width，例如小屏下减慢速度（15s → 20s）；
- 性能优化：确保 .scroll-container 无重排触发（如避免读取 offsetWidth 后立即写入 style），本方案中 useEffect 写入是安全的；
- 无限循环原理：动画终点 translateX(-100%) 表示向左移动“容器自身宽度”，当内容总宽 > 视口时，最后一张卡片刚好滑出左侧，而首张卡片已在右侧准备入场，视觉上形成无缝轮播；
- 扩展性提示：如需支持双向滚动、变速、或手动拖拽暂停，可封装为自定义 Hook（如 useAutoScroll），接收 duration、direction、pauseOnHover 等参数。
该方案已验证于 chrome/firefox/safari，无第三方依赖，零 bundle 增量，兼顾可维护性与运行时性能，是当前 React 生态中实现自动水平滚动的推荐范式。