Tailwind on HanGR的碎碎念

CSS 无限滚动 Marquee 动画实现

Wed, 22 Jan 2025 00:00:00 +0000

不用任何 JS 库，纯 CSS 实现无缝循环滚动。这是 RuiToolAI 客户评价组件的实现记录。

效果目标

卡片从右向左无限滚动
滚动无缝衔接，看不出循环点
鼠标悬停时暂停
两侧有渐变遮罩，边缘自然淡出
支持暗色模式

核心原理

Marquee 动画的本质是：用 CSS translateX 把一排元素从 0 移动到 -50%，然后瞬间重置到 0，循环播放。

为什么是 -50%？因为我把内容复制了一份，总宽度是原来的 2 倍。移动 -50% 正好是一份内容的宽度，重置后用户看不出来。

1
2
3
4
5


原始内容：[A][B][C][D]
复制后： [A][B][C][D][A][B][C][D]
 ←←←←←←←←←←←←←←←←←←←←
动画：从 translateX(0) 到 translateX(-50%)
重置：瞬间回到 translateX(0)，用户看到的还是 [A][B][C][D]

基础实现

先用纯 CSS 实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


/* 定义 marquee 动画 */
@keyframes marquee {
 from {
 transform: translateX(0);
 }
 to {
 transform: translateX(-50%);
 }
}

.marquee-track {
 display: flex;
 animation: marquee 30s linear infinite;
}

/* 容器需要 overflow-hidden */
.marquee-container {
 overflow: hidden;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<div class="marquee-container">
 <div class="marquee-track">
 <!-- 原始内容 -->
 <div class="item">卡片 1</div>
 <div class="item">卡片 2</div>
 <div class="item">卡片 3</div>
 <!-- 复制一份，实现无缝循环 -->
 <div class="item">卡片 1</div>
 <div class="item">卡片 2</div>
 <div class="item">卡片 3</div>
 </div>
</div>

无缝循环的关键：复制元素

在 React 里，用 JS 复制数组：

1
2
3


const items = ["卡片1", "卡片2", "卡片3"];
// 复制一份，总共 6 个元素
const doubled = [...items, ...items];

1
2
3
4
5
6
7


<div className="flex animate-marquee">
 {doubled.map((item, i) => (
 <div key={i} className="flex-shrink-0 w-80">
 {item}
 </div>
 ))}
</div>

flex-shrink-0 很重要，防止卡片被压缩。

加入 Tailwind

在 tailwind.config.ts 里注册自定义动画：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
 theme: {
 extend: {
 keyframes: {
 marquee: {
 from: { transform: "translateX(0)" },
 to: { transform: "translateX(-50%)" },
 },
 },
 animation: {
 // 30s 速度，linear 匀速，infinite 无限循环
 marquee: "marquee 30s linear infinite",
 },
 },
 },
};

然后直接用 animate-marquee 类名：

1
2
3


<div className="flex animate-marquee">
 {/* 卡片 */}
</div>

hover 暂停

Tailwind 支持 [animation-play-state:paused] 这种任意值写法：

1
2
3


<div className="flex animate-marquee hover:[animation-play-state:paused]">
 {/* 鼠标悬停时暂停 */}
</div>

但有个问题：鼠标悬停在卡片上时，事件冒泡到父元素，动画暂停。但如果鼠标悬停在卡片之间的间隙，动画不会暂停。

更好的做法是把 hover 监听放在外层容器：

1
2
3
4
5


<div className="group overflow-hidden">
 <div className="flex animate-marquee group-hover:[animation-play-state:paused]">
 {/* 卡片 */}
 </div>
</div>

group + group-hover: 让父元素的 hover 状态控制子元素的动画。

两侧渐变遮罩

渐变遮罩让边缘自然淡出，视觉上更好看：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


<div className="relative overflow-hidden max-w-7xl mx-auto">
 {/* 左侧遮罩 */}
 <div
 className="absolute left-0 top-0 bottom-0 w-24 z-10 pointer-events-none
 bg-gradient-to-r from-background to-transparent"
 />

 {/* 右侧遮罩 */}
 <div
 className="absolute right-0 top-0 bottom-0 w-24 z-10 pointer-events-none
 bg-gradient-to-l from-background to-transparent"
 />

 {/* 滚动内容 */}
 <div className="flex gap-6 animate-marquee">
 {/* 卡片 */}
 </div>
</div>

关键细节：

pointer-events-none：遮罩不拦截鼠标事件，hover 暂停仍然有效
from-background：用语义化颜色，暗色模式自动适配
z-10：遮罩在卡片上层

响应式和暗色模式

卡片宽度在移动端可以小一点：

1
2
3


<div className="flex-shrink-0 w-72 sm:w-80 p-4 sm:p-6 rounded-xl border border-border bg-card">
 <p className="text-sm sm:text-base text-muted-foreground">{content}</p>
</div>

暗色模式用语义化颜色，不需要额外的 dark: 前缀：

1
2


// bg-card、text-card-foreground、border-border 都会随主题自动切换
<div className="bg-card text-card-foreground border border-border">

完整组件代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84


// src/components/landing/testimonials.tsx
"use client";

const testimonials = [
 {
 content: "RuiToolAI 的图片生成速度非常快，质量也很高。",
 name: "Sarah Chen",
 role: "UI 设计师",
 avatar: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=100",
 },
 {
 content: "积分制度很合理，按需购买，不浪费。",
 name: "Marcus Johnson",
 role: "内容创作者",
 avatar: "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=100",
 },
 // ... 更多评价
];

// 复制一份实现无缝循环
const doubled = [...testimonials, ...testimonials];

export function Testimonials() {
 return (
 <section className="py-16 bg-background overflow-hidden">
 <div className="max-w-7xl mx-auto px-4 mb-12">
 <h2 className="text-3xl font-bold text-center text-foreground">
 用户怎么说
 </h2>
 <p className="text-center text-muted-foreground mt-4">
 来自真实用户的反馈
 </p>
 </div>

 {/* 滚动区域，限制最大宽度 */}
 <div className="relative max-w-7xl mx-auto overflow-hidden group">
 {/* 左侧渐变遮罩 */}
 <div className="absolute left-0 top-0 bottom-0 w-24 z-10 pointer-events-none bg-gradient-to-r from-background to-transparent" />

 {/* 右侧渐变遮罩 */}
 <div className="absolute right-0 top-0 bottom-0 w-24 z-10 pointer-events-none bg-gradient-to-l from-background to-transparent" />

 {/* 滚动轨道 */}
 <div className="flex gap-6 animate-marquee group-hover:[animation-play-state:paused]">
 {doubled.map((item, i) => (
 <div
 key={i}
 className="flex-shrink-0 w-80 p-6 rounded-xl border border-border bg-card shadow-sm"
 >
 {/* 星级评分 */}
 <div className="flex gap-1 mb-3">
 {Array.from({ length: 5 }).map((_, j) => (
 <span key={j} className="text-yellow-400 text-sm">
 ★
 </span>
 ))}
 </div>

 {/* 评价内容 */}
 <p className="text-muted-foreground text-sm leading-relaxed mb-4">
 "{item.content}"
 </p>

 {/* 用户信息 */}
 <div className="flex items-center gap-3">
 <img
 src={item.avatar}
 alt={item.name}
 className="w-10 h-10 rounded-full object-cover"
 />
 <div>
 <p className="font-medium text-foreground text-sm">
 {item.name}
 </p>
 <p className="text-xs text-muted-foreground">{item.role}</p>
 </div>
 </div>
 </div>
 ))}
 </div>
 </div>
 </section>
 );
}

常见问题

Q：滚动速度怎么调？

修改 tailwind.config.ts 里的动画时长：

1
2
3


animation: {
 marquee: "marquee 20s linear infinite", // 20s 更快，60s 更慢
},

Q：卡片数量少时循环点很明显怎么办？

复制更多份：

1
2
3


// 复制 3 份而不是 2 份
const tripled = [...items, ...items, ...items];
// 动画移动到 -33.33% 而不是 -50%

或者增加卡片数量，让一屏显示不完。

Q：移动端性能差怎么办？

用 will-change: transform 开启 GPU 加速：

1
2
3


.marquee-track {
 will-change: transform;
}

Tailwind 里：

1

<div className="flex animate-marquee will-change-transform">

Q：能反向滚动吗（从左向右）？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// tailwind.config.ts
keyframes: {
 "marquee-reverse": {
 from: { transform: "translateX(-50%)" },
 to: { transform: "translateX(0)" },
 },
},
animation: {
 "marquee-reverse": "marquee-reverse 30s linear infinite",
},

总结

纯 CSS Marquee 的核心就三步：

复制内容：把数组 [...items, ...items]，总宽度翻倍
定义动画：translateX(0) → translateX(-50%)，linear，infinite
overflow-hidden：容器裁剪，只显示一半内容

加上渐变遮罩和 hover 暂停，效果就很完整了。

参考资源

Tailwind CSS 暗色模式从零搭建

Sat, 23 Nov 2024 00:00:00 +0000

暗色模式不只是加个 dark: 前缀那么简单。这篇记录我在 RuiToolAI 里搭建完整暗色模式体系的过程。

为什么暗色模式容易搞乱

暗色模式最常见的问题：

颜色硬编码：text-gray-900 在暗色下看不见
闪烁（FOUC）：页面加载时先显示亮色再切换到暗色
图片/图标不适配：亮色图标在暗色背景上消失
第三方组件不跟随：自己的组件暗色了，Shadcn 组件还是亮色

Tailwind 暗色模式配置

Tailwind 支持两种暗色模式策略：

1
2
3
4
5
6
7
8


// tailwind.config.ts
export default {
 // 方案一：跟随系统（media）
 darkMode: "media",

 // 方案二：手动切换（class）—— 推荐
 darkMode: "class",
};

推荐用 class 方案，因为：

用户可以手动切换，不受系统设置影响
可以持久化到 localStorage
SSR 时可以从 cookie 读取，避免闪烁

CSS 变量 + Tailwind 的组合方案

硬编码颜色是暗色模式的大敌。正确做法是用 CSS 变量定义语义化颜色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


/* src/app/globals.css */
@layer base {
 :root {
 --background: 0 0% 100%;
 --foreground: 222.2 84% 4.9%;
 --card: 0 0% 100%;
 --card-foreground: 222.2 84% 4.9%;
 --primary: 221.2 83.2% 53.3%;
 --primary-foreground: 210 40% 98%;
 --muted: 210 40% 96.1%;
 --muted-foreground: 215.4 16.3% 46.9%;
 --border: 214.3 31.8% 91.4%;
 --radius: 0.5rem;
 }

 .dark {
 --background: 222.2 84% 4.9%;
 --foreground: 210 40% 98%;
 --card: 222.2 84% 4.9%;
 --card-foreground: 210 40% 98%;
 --primary: 217.2 91.2% 59.8%;
 --primary-foreground: 222.2 47.4% 11.2%;
 --muted: 217.2 32.6% 17.5%;
 --muted-foreground: 215 20.2% 65.1%;
 --border: 217.2 32.6% 17.5%;
 }
}

然后在 tailwind.config.ts 里把这些变量映射成 Tailwind 颜色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
 darkMode: "class",
 theme: {
 extend: {
 colors: {
 background: "hsl(var(--background))",
 foreground: "hsl(var(--foreground))",
 card: {
 DEFAULT: "hsl(var(--card))",
 foreground: "hsl(var(--card-foreground))",
 },
 primary: {
 DEFAULT: "hsl(var(--primary))",
 foreground: "hsl(var(--primary-foreground))",
 },
 muted: {
 DEFAULT: "hsl(var(--muted))",
 foreground: "hsl(var(--muted-foreground))",
 },
 border: "hsl(var(--border))",
 },
 },
 },
};

这样写组件时只需要用语义化类名，暗色模式自动切换：

1
2
3
4


// 不需要写 dark: 前缀
<div className="bg-background text-foreground">
 <p className="text-muted-foreground">副标题</p>
</div>

主题切换实现

避免闪烁的关键

闪烁（FOUC）发生在：服务端渲染了亮色 HTML，客户端 JS 加载后才切换到暗色，用户看到一闪。

解决方案：在 <head> 里内联一段脚本，在页面渲染前就设置好 class：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// src/app/layout.tsx
export default function RootLayout({
 children,
}: {
 children: React.ReactNode;
}) {
 return (
 <html lang="zh" suppressHydrationWarning>
 <head>
 {/* 内联脚本，在 HTML 解析时立即执行，避免闪烁 */}
 <script
 dangerouslySetInnerHTML={{
 __html: `
 (function() {
 try {
 var theme = localStorage.getItem('theme');
 if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
 document.documentElement.classList.add('dark');
 }
 } catch (e) {}
 })();
 `,
 }}
 />
 </head>
 <body>{children}</body>
 </html>
 );
}

suppressHydrationWarning 是必须的，因为服务端和客户端的 class 可能不同。

主题切换组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// src/components/theme-toggle.tsx
"use client";
import { useEffect, useState } from "react";
import { SunIcon, MoonIcon } from "@heroicons/react/24/outline";

export function ThemeToggle() {
 const [isDark, setIsDark] = useState(false);

 useEffect(() => {
 // 初始化时读取当前主题
 setIsDark(document.documentElement.classList.contains("dark"));
 }, []);

 function toggle() {
 const next = !isDark;
 setIsDark(next);
 if (next) {
 document.documentElement.classList.add("dark");
 localStorage.setItem("theme", "dark");
 } else {
 document.documentElement.classList.remove("dark");
 localStorage.setItem("theme", "light");
 }
 }

 return (
 <button
 onClick={toggle}
 className="rounded-md p-2 hover:bg-muted transition-colors"
 aria-label={isDark ? "切换到亮色模式" : "切换到暗色模式"}
 >
 {isDark ? (
 <SunIcon className="h-5 w-5" />
 ) : (
 <MoonIcon className="h-5 w-5" />
 )}
 </button>
 );
}

Shadcn UI 的暗色模式集成

Shadcn UI 的组件本身已经支持暗色模式，因为它们内部用的就是 CSS 变量（bg-background、text-foreground 等）。

只要你的 CSS 变量配置正确，Shadcn 组件会自动跟随主题切换。

但有一个坑：Shadcn 的 cn() 工具函数。

1
2
3
4
5
6
7


// src/lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
 return twMerge(clsx(inputs));
}

当你用 dark: 前缀覆盖 Shadcn 组件的默认样式时，twMerge 会正确处理冲突，不会出现样式叠加问题。

常见坑点

坑 1：图片在暗色下太亮

1
2
3
4
5
6


// 给图片加暗色滤镜
<img
 src="/logo.png"
 className="dark:brightness-90 dark:invert"
 alt="Logo"
/>

坑 2：渐变在暗色下不好看

1
2


// 亮色：浅蓝渐变；暗色：深蓝渐变
<div className="bg-gradient-to-r from-blue-50 to-indigo-50 dark:from-blue-950 dark:to-indigo-950">

坑 3：边框在暗色下消失

1
2
3
4


// 用语义化 border 颜色
<div className="border border-border">
 {/* border 颜色会随主题切换 */}
</div>

坑 4：第三方库的弹窗/Portal 不跟随主题

有些第三方库把弹窗挂载到 document.body，不在 .dark 类的作用范围内。

解决方案：把 .dark 类加到 <html> 而不是 <body>，这样所有子元素都能继承。

实战：给 Testimonials 组件加暗色支持

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


// src/components/landing/testimonials.tsx
export function Testimonials() {
 return (
 <section className="py-16 bg-background">
 <div className="max-w-7xl mx-auto px-4">
 <h2 className="text-3xl font-bold text-center text-foreground mb-12">
 用户评价
 </h2>

 {/* 滚动容器 */}
 <div className="relative overflow-hidden">
 {/* 左侧渐变遮罩 */}
 <div className="absolute left-0 top-0 bottom-0 w-24 z-10 bg-gradient-to-r from-background to-transparent" />

 {/* 右侧渐变遮罩 */}
 <div className="absolute right-0 top-0 bottom-0 w-24 z-10 bg-gradient-to-l from-background to-transparent" />

 <div className="flex gap-6 animate-marquee hover:[animation-play-state:paused]">
 {testimonials.map((item, i) => (
 <div
 key={i}
 className="flex-shrink-0 w-80 p-6 rounded-xl border border-border bg-card text-card-foreground shadow-sm"
 >
 <p className="text-muted-foreground mb-4">{item.content}</p>
 <div className="flex items-center gap-3">
 <img
 src={item.avatar}
 alt={item.name}
 className="w-10 h-10 rounded-full object-cover"
 />
 <div>
 <p className="font-medium text-foreground">{item.name}</p>
 <p className="text-sm text-muted-foreground">{item.role}</p>
 </div>
 </div>
 </div>
 ))}
 </div>
 </div>
 </div>
 </section>
 );
}

注意渐变遮罩用的是 from-background，这样在暗色模式下遮罩颜色也会自动切换，不会出现白色遮罩盖在暗色背景上的问题。

总结

搭建完整暗色模式体系的关键步骤：

CSS 变量定义语义化颜色：:root 和 .dark 分别定义
Tailwind 映射 CSS 变量：tailwind.config.ts 里配置
内联脚本避免闪烁：在 <head> 里提前设置 class
组件用语义化类名：bg-background、text-foreground，而不是 bg-white、text-gray-900
渐变遮罩用语义化颜色：from-background 而不是 from-white