本文介绍一种基于 CSS @keyframes + transform: translateX() 的纯声明式方案，实现 React 中卡片列表的无缝、自动、无限水平滚动，避免 JS 动画性能开销，支持响应式与动态内容。
本文介绍一种基于 CSS `@keyframes` + `transform: translateX()` 的纯声明式方案，实现 React 中卡片列表的无缝、自动、无限水平滚动，避免 JS 动画性能开销，支持响应式与动态内容。
在构建信息流式 UI（如国家/品牌轮播墙、标签云、推荐卡片栏）时，自动水平滚动是一种常见且高吸引力的交互形式。相比手动触发或依赖第三方库，一个轻量、可复用、性能友好的原生方案更具长期价值。本文推荐并详解一种以 CSS 动画为核心、React 仅负责状态协调的最佳实践——它规避了 requestAnimationFrame 手动管理位移、边界重置及帧率不稳定等常见问题，同时保持完全可控与可扩展性。
✅ 核心思路：CSS 驱动 + 容器宽度自适应
动画逻辑完全交由 CSS @keyframes 处理，React 层只需：
构建 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
- 获取容器真实总宽度（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 手动位移更现代、更可靠的选择。
立即学习“前端免费学习笔记（深入）”；
