本文介绍如何在 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
构建 Shopify 嵌入式应用（Embedded App）的开发技能：基于 @shopify/shopify-app-react-router + React Router v7 + Admin API 2026-04。覆盖 shopifyApp 配置、authenticate.admin 的 GraphQL/REST 调用、Webhook 校验、Session 存储、订阅计费、App Bridge 导航、部署，并新增：适用场景判断、安全最佳实践、错误处理与容错、最佳实践、常见问题 FAQ、高级场景。G
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 生态中实现自动水平滚动的推荐范式。
