本文介绍一种基于 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（卡片子组件，保持轻量无状态）
构建 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
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 水平自动滚动场景的推荐实践。
