本文介绍一种基于纯 CSS 动画 + React 动态宽度计算的自动水平滚动方案，替代易出错的 requestAnimationFrame 手动位移逻辑，解决卡片溢出不滚动、动画卡顿、重置异常等问题，兼顾性能与可扩展性。
本文介绍一种基于纯 CSS 动画 + React 动态宽度计算的自动水平滚动方案，替代易出错的 `requestAnimationFrame` 手动位移逻辑，解决卡片溢出不滚动、动画卡顿、重置异常等问题，兼顾性能与可扩展性。
在构建横向信息流（如国家卡片轮播、产品推荐栏、标签云等）时，自动无缝水平滚动是常见需求。但直接用 transform + useAnimationFrame 手动更新 position 容易陷入坐标计算错误、边界重置失效、响应式失配等问题——正如原始代码中 newPosition
更健壮、更符合现代 React 实践的解法是：将滚动逻辑交由 CSS @keyframes 驱动，React 仅负责动态测量容器真实内容宽度并触发动画播放。这种方式利用浏览器原生合成层（Compositor），避免 JS 主线程阻塞，动画更流畅，代码更简洁，也天然支持暂停/恢复、速度调节等扩展能力。
✅ 推荐实现：CSS 动画 + scrollWidth 自适应
核心思路：
立即学习“前端免费学习笔记（深入）”；
- 使用 display: flex 布局卡片容器，允许子元素自然流式排列；
- 容器设为 overflow: visible 并通过 transform: translateX() 控制起始位置；
- 利用 @keyframes 定义从右到左的平滑位移动画，终点为 -100%（即向左移动自身完整内容宽度）；
- React 中用 useRef 获取容器 DOM，通过 ref.current.scrollWidth 精确获取所有卡片总宽度，并动态设置动画终点。
? 示例代码（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 [animationState, setAnimationState] = useState("paused");
useEffect(() => {
if (containerRef.current) {
// 关键：获取真实滚动宽度（含所有卡片+间距）
const width = containerRef.current.scrollWidth;
// 启动动画（也可通过 className 控制，此处用内联样式更直观）
setAnimationState("running");
}
}, []);
return (
<div className="App">
<div
ref={containerRef}
className="cards-container"
style={{ animationPlayState: animationState }}
>
{data.map((item, index) => (
<Card key={index} cardName={item.Name} />
))}
</div>
</div>
);
}? 样式文件（styles.css）
.App {
overflow: hidden; /* 隐藏超出区域，实现“视窗”效果 */
padding: 20px 0;
}
.cards-container {
display: flex;
gap: 16px; /* 推荐用 gap 替代 margin，更可控 */
/* 起始位置：从视口右侧完全进入 */
transform: translateX(100vw);
/* 动画：10秒匀速从右至左，无缝循环 */
animation: scrollHorizontal 10s linear infinite;
animation-play-state: paused; /* 初始暂停，useEffect 中激活 */
}
/* 卡片基础样式（确保尺寸一致） */
.card {
min-width: 200px;
height: 200px;
background: #fff;
border-radius: 15px;
box-shadow: 0 1px 4px 1px rgba(158, 151, 151, 0.25);
padding: 12px;
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
}
.card .fs-5 {
font-size: 1.25rem;
margin: 0;
}
/* 核心动画：从右边界开始，向左移动自身全部内容宽度 */
@keyframes scrollHorizontal {
from {
transform: translateX(100vw);
}
to {
transform: translateX(calc(-1 * var(--container-width, 100%)));
}
}
/* ⚠️ 注意：CSS 变量需在 JS 中注入（见下方增强技巧） */? 进阶技巧：动态注入 --container-width
若需更高精度（尤其当卡片宽高不固定时），可在 useEffect 中将 scrollWidth 注入 CSS 变量：
useEffect(() => {
if (containerRef.current) {
const width = containerRef.current.scrollWidth;
containerRef.current.style.setProperty("--container-width", `${width}px`);
setAnimationState("running");
}
}, []);此时 CSS 中 to 值改为：
to { transform: translateX(calc(-1 * var(--container-width))); }⚠️ 关键注意事项
- 避免 margin 导致宽度误判：Flex 容器的 scrollWidth 包含子元素 margin，但 gap 不计入。建议统一使用 gap 控制间距，或在计算后手动补偿 margin。
- 响应式中断处理：窗口缩放可能改变 scrollWidth，如需实时响应，可监听 resize 事件并重新设置变量（注意防抖）。
- 暂停/播放控制：通过切换 animation-play-state: paused/running 即可控制启停，适合 hover 暂停等交互。
- 性能提示：transform 和 opacity 是仅触发布局（Layout）和绘制（Paint）的 CSS 属性，本方案全程使用 transform，确保 60fps 流畅滚动。
✅ 总结
相比手动 requestAnimationFrame 位移，CSS 驱动的自动滚动具备三大优势：
? 更高性能：由 GPU 加速，不阻塞主线程；
? 更强鲁棒性：无需维护状态、边界判断和重置逻辑；
? 更易维护：动画时长、方向、缓动函数均可在 CSS 中集中配置，React 层专注数据与生命周期。
该方案已验证兼容 Chrome/Firefox/Safari，适用于任意数量卡片，且天然支持 SSR（服务端渲染）——只需确保 useEffect 中的 DOM 操作不执行于服务端即可。
