从零搭建 OKX 官方活动监控仪表盘：React + Vite + TailwindCSS 实战心得

本文记录了使用 React 18 + Vite + TailwindCSS 从零搭建一个深色主题监控仪表盘的完整过程，分享在组件设计、状态管理、视觉打磨和工程化方面的实战经验。

一、项目背景

在加密货币交易领域，交易所官方活动（交易大赛、空投、上新币、公告等）信息分散在不同页面，用户往往需要频繁切换才能了解全部活动动态。如果能把这些信息聚合到一个监控仪表盘上，一目了然地看到所有活动状态、奖励和参与入口，将极大提升信息获取效率。

基于这个想法，我决定搭建一个 OKX 官方活动监控仪表盘——一个深色主题的数据监控大屏，类似 Grafana 的视觉风格，将活动信息以结构化、可视化的方式呈现。

二、技术选型与思考

为什么选 React + Vite + TailwindCSS？

核心考量：监控仪表盘的 UI 变化频繁、样式定制化程度高，TailwindCSS 的原子化写法在这种场景下优势明显——改一个颜色、调一个间距，直接在 JSX 里改 class 名即可，不需要跳到 CSS 文件找选择器。

一个容易被忽略的配置：safelist

TailwindCSS 默认会扫描源码中出现的 class 名来生成 CSS。但如果 class 名是动态拼接的（比如 bg-${color}-400），Tailwind 在构建时无法识别，最终生成的 CSS 里不会包含这些 class，导致样式丢失。

// tailwind.config.js
safelist: [
  'bg-blue-400', 'bg-green-400', 'bg-yellow-400', 'bg-red-400',
  'bg-cyan-400', 'bg-purple-400', 'bg-orange-400', 'bg-pink-400',
  'bg-blue-500/5', 'bg-green-500/5', 'bg-yellow-500/5', 'bg-red-500/5',
  'shadow-blue-500/20', 'shadow-green-500/20', 'shadow-yellow-500/20', 'shadow-red-500/20',
],

这是我在开发中踩的第一个坑：概览卡片的背景色和阴影用了模板字符串拼接，本地开发时一切正常（因为 Tailwind dev server 会全量生成），但一旦 build 后部署，颜色就全丢了。解决方案就是在 safelist 里显式声明这些动态 class。

经验：如果你在 Tailwind 里用了动态 class 名，一定要加 safelist。这是 Tailwind 文档里有写但很容易忽略的细节。

三、架构设计

项目采用四层架构，职责清晰分离：

数据层 (mockData.js)     → 12条活动数据 + 8条公告 + 类型定义
    ↓
工具层 (helpers.js)      → 状态判断、类型映射、倒计时计算、时间格式化
    ↓
组件层 (7个组件)         → TopBar / OverviewCards / ActivityTable / TypeFilter
                           AnnouncementTicker / ActivityTimeline / RefreshControl
    ↓
应用层 (App.jsx)         → 状态管理 + 自动刷新 + 组件组合

为什么把 helpers 单独抽出来？

一开始我把状态判断和格式化函数直接写在组件里。但很快发现 ActivityTable 和 ActivityTimeline 都需要 getStatusInfo，ActivityTable 还需要 getCountdown。如果不抽出来，要么重复写，要么在组件间互相 import，形成耦合。

抽成独立的 helpers.js 后，所有组件都从同一个地方取工具函数，逻辑统一，修改时只改一处。这个原则看起来简单，但在实际开发中很容易偷懒把函数写在当前组件里——直到第二个组件需要它时才后悔。

四、核心实现细节

1. 状态管理：useState + useMemo 的组合拳

监控仪表盘的核心需求是：数据变化时，统计自动更新；筛选变化时，列表自动过滤。这涉及多个派生状态。

// App.jsx 核心状态
const [activities, setActivities] = useState(mockActivities)
const [activeType, setActiveType] = useState('all')
const [autoRefresh, setAutoRefresh] = useState(true)

// 派生状态1：统计数据（依赖 activities）
const stats = useMemo(() => ({
  total: activities.length,
  active: activities.filter(a => a.status === 'active').length,
  upcoming: activities.filter(a => a.status === 'upcoming').length,
  ended: activities.filter(a => a.status === 'ended').length,
}), [activities])

// 派生状态2：筛选后的列表（依赖 activities + activeType）
const filteredActivities = useMemo(() => {
  if (activeType === 'all') return activities
  return activities.filter(a => a.type === activeType)
}, [activities, activeType])

关键决策：stats 的依赖数组是 [activities]，filteredActivities 的依赖数组是 [activities, activeType]。这意味着只有数据或筛选条件变化时才重新计算，避免每次渲染都做无用的 filter 操作。

对于 12 条数据来说，性能差异微乎其微。但这个模式在数据量增大时（比如 1000+ 条活动）会显著减少渲染开销。养成用 useMemo 的习惯，是在为未来扩展买保险。

2. 自动刷新：useEffect + setInterval 的正确写法

const handleRefresh = useCallback(() => {
  setConnected(true)
  setLastRefresh(new Date())
  setFlashKey(k => k + 1)  // 触发数字闪烁动画
  // 重新排序：进行中 → 即将开始 → 已结束
  const shuffled = [...mockActivities].sort((a, b) => {
    const order = { active: 0, upcoming: 1, ended: 2 }
    return (order[a.status] || 3) - (order[b.status] || 3)
  })
  setActivities(shuffled)
}, [])

useEffect(() => {
  if (!autoRefresh) return
  const timer = setInterval(() => handleRefresh(), 30000)
  return () => clearInterval(timer)  // 清理函数，防止内存泄漏
}, [autoRefresh, handleRefresh])

三个细节值得注意：

1. handleRefresh 用 useCallback 包裹：如果不包裹，每次渲染都会创建新函数引用，useEffect 的依赖 handleRefresh 就会变化，导致 setInterval 被反复清除和重建。用 useCallback 后函数引用稳定，定时器只在 autoRefresh 变化时重建。

2. 清理函数 return () => clearInterval(timer)：这是 React Hook 的基本规范，但在实际开发中经常被遗忘。不写清理函数，组件卸载后定时器还在跑，会造成内存泄漏和 setState on unmounted component 警告。

3. flashKey 的妙用：刷新后数字需要闪烁一下提示用户"数据更新了"。通过 setFlashKey(k => k + 1) 改变 key 值，触发组件的 animate-flash 动画重新执行。这是 React 中"强制重新触发动画"的常用技巧。

3. 倒计时计算：处理时间差的正确姿势

export function getCountdown(endTime) {
  const end = parseTime(endTime)
  const now = new Date()
  const diff = end - now
  if (diff <= 0) return '已结束'
  const days = Math.floor(diff / 86400000)
  const hours = Math.floor((diff % 86400000) / 3600000)
  const mins = Math.floor((diff % 3600000) / 60000)
  if (days > 0) return `${days}天 ${hours}小时`
  if (hours > 0) return `${hours}小时 ${mins}分钟`
  return `${mins}分钟`
}

踩坑记录：parseTime 函数里有一行 new Date(str.replace(/-/g, '/'))。这是因为 Safari 和旧版浏览器不支持 new Date('2026-10-08 00:00:00') 这种格式（带空格的 ISO 格式），但支持 new Date('2026/10/08 00:00:00')。把 - 替换成 / 是跨浏览器兼容的经典处理。

在现代 Chrome 中这行替换看起来多余，但如果你的用户可能用 Safari 或移动端浏览器，这个处理是必须的。

4. 状态颜色映射：用配置对象替代 if-else

export function getStatusInfo(status) {
  switch (status) {
    case 'active':
      return { label: '进行中', color: 'green', dotClass: 'bg-green-400',
               badgeClass: 'bg-green-500/15 text-green-400 border-green-500/30' }
    case 'upcoming':
      return { label: '即将开始', color: 'yellow', dotClass: 'bg-yellow-400',
               badgeClass: 'bg-yellow-500/15 text-yellow-400 border-yellow-500/30' }
    case 'ended':
      return { label: '已结束', color: 'red', dotClass: 'bg-red-400',
               badgeClass: 'bg-red-500/15 text-red-400 border-red-500/30' }
    default:
      return { label: '未知', color: 'gray', dotClass: 'bg-gray-400',
               badgeClass: 'bg-gray-500/15 text-gray-400 border-gray-500/30' }
  }
}

这里用 switch 返回统一结构的对象，而不是散落的 if-else。好处是：所有状态的视觉属性（颜色、class 名）集中在一处管理。如果设计师说"把’即将开始’改成蓝色"，我只改这一处，不用全局搜索替换。

五、视觉设计：深色仪表盘的打磨细节

1. 卡片发光效果

.dashboard-card {
  @apply bg-card-bg border border-card-border rounded-xl backdrop-blur-sm;
  box-shadow: 0 0 12px rgba(59, 130, 246, 0.08),
              inset 0 1px 0 rgba(255, 255, 255, 0.03);
}
.dashboard-card:hover {
  border-color: rgba(59, 130, 246, 0.4);
  box-shadow: 0 0 24px rgba(59, 130, 246, 0.15),
              inset 0 1px 0 rgba(255, 255, 255, 0.05);
}

深色主题的卡片不能只是简单地把背景改黑——那样会显得死板。关键在于层次感：

• backdrop-blur-sm：半透明背景 + 毛玻璃效果，让卡片有"浮在背景之上"的感觉
• box-shadow 外阴影：蓝色微光，暗示科技感
• inset 内阴影：顶部一条极淡的白色高光，模拟光照从上方打下来的效果
• hover 时阴影增强 + 边框变亮：给用户"这个卡片是可交互的"的视觉反馈

2. 自定义滚动条

::-webkit-scrollbar {
  width: 8px;
  height: 8px;
}
::-webkit-scrollbar-track {
  background: rgba(15, 23, 42, 0.5);
}
::-webkit-scrollbar-thumb {
  background: rgba(100, 116, 139, 0.4);
  border-radius: 4px;
}

深色主题下浏览器默认滚动条是白色的，非常刺眼。自定义滚动条颜色使其融入深色背景，是深色主题的必备操作。表格区域还用了更细的 4px 滚动条（.scrollbar-thin），避免占用过多空间。

3. 动画体系

在 tailwind.config.js 中定义了 5 个自定义动画：

设计原则：动画要克制，不能让页面"动个不停"让人眼花。这里只有 5 个动画，每个都有明确的功能目的——不是"为了好看而动"，而是"通过动来传达信息"（闪烁=数据更新了，脉冲=系统在线，渐入=新内容加载）。

六、响应式布局策略

// 概览卡片：移动端2列，桌面端4列
<div className="grid grid-cols-2 lg:grid-cols-4 gap-3 md:gap-4">

// 主内容区：表格占2/3，时间线占1/3（仅大屏）
<div className="grid grid-cols-1 xl:grid-cols-3 gap-3 md:gap-4">
  <div className="xl:col-span-2"><ActivityTable /></div>
  <div className="xl:col-span-1"><ActivityTimeline /></div>
</div>

断点选择：

• grid-cols-2（默认）：手机上 2 列卡片，不会太挤
• lg:grid-cols-4（≥1024px）：平板/小笔记本上 4 列，充分利用宽度
• xl:grid-cols-3（≥1280px）：大屏上表格和时间线并排，小屏则上下堆叠

经验：不要从手机开始设计再往上适配（mobile-first 听起来好但容易陷入"手机优先"的思维），对于监控仪表盘这类产品，桌面端才是主要使用场景。我建议先设计桌面布局，再往下适配移动端。TailwindCSS 的 xl: 前缀让这个过程很自然。

七、数据设计：Mock 数据的字段考量

{
  id: 1,
  name: 'BTC 交易大赛 - 金秋狂欢',
  type: 'trading',           // 类型：用于筛选和图标
  startTime: '2026-10-08 00:00:00',
  endTime: '2026-10-20 23:59:59',
  status: 'active',          // 状态：active/upcoming/ended
  reward: '50,000 USDT 奖池',
  description: '活动期间累计 BTC 交易量排名...',
  link: 'https://www.okx.com/...',
  priority: 'high',          // 优先级：high/medium/low
}

字段设计的三个原则：

1. status 用枚举值而非中文：用 active 而不是 '进行中'，代码里判断 a.status === 'active' 比 a.status === '进行中' 更可靠（不怕打错中文），也方便后续对接真实 API。

2. type 和 priority 同理：用英文枚举值，显示时再通过 getTypeInfo / getPriorityInfo 映射成中文标签和颜色。

3. link 独立字段：不要把链接嵌在 description 里用正则提取。独立字段让表格里的"参与"按钮可以直接 href={act.link}，干净利落。

八、工程化经验

端口冲突处理

开发时遇到端口 5173（Vite 默认端口）被占用的情况。与其手动找端口，不如在启动脚本里自动检测空闲端口。从 5173 开始找，找到第一个空闲端口就返回。在实际开发中，沙箱环境里端口经常被其他进程占用，自动检测比硬编码端口更可靠。

项目结构规范

src/
├── main.jsx              # 入口，只负责挂载
├── App.jsx               # 主应用，状态管理 + 布局
├── index.css             # 全局样式 + Tailwind 指令
├── data/mockData.js      # 数据层：mock 数据 + 类型定义
├── utils/helpers.js      # 工具层：纯函数，无副作用
└── components/           # 组件层：每个组件一个文件
    ├── TopBar.jsx
    ├── OverviewCards.jsx
    ├── ActivityTable.jsx
    ├── TypeFilter.jsx
    ├── AnnouncementTicker.jsx
    ├── ActivityTimeline.jsx
    └── RefreshControl.jsx

原则：每个组件一个文件，文件名 = 组件名。不要把多个组件塞在一个文件里——即使它们看起来"很小"。当你需要 import TopBar from './components/TopBar' 时，路径和文件名一致是最直觉的。

九、总结与反思

做对了的

• 技术选型精准：React + Vite + TailwindCSS 三件套对仪表盘类项目是最佳组合，开发效率极高
• 架构分层清晰：数据/工具/组件/应用四层分离，修改任何一层不影响其他层
• 视觉打磨到位：深色主题不是改个背景色就完事，发光、毛玻璃、动画、滚动条每个细节都要照顾
• 状态管理克制：没有引入 Redux/Zustand，纯 useState + useMemo 足够用，避免过度工程化

可以改进的

• Mock 数据应抽成 JSON 文件：目前 mock 数据直接写在 JS 文件里，如果后续对接真实 API，替换起来不够干净。更好的做法是 mock 数据放在 .json 文件里，通过 fetch 加载，切换真实 API 时只改 URL。
• 缺少单元测试：helpers.js 里的纯函数（getCountdown、getStatusInfo）非常适合写单元测试，尤其是 getCountdown 涉及时间计算，边界条件多，没有测试心里不踏实。
• 表格虚拟滚动：目前 12 条数据直接渲染没问题，但如果活动数量增长到几百条，需要引入 react-window 或 @tanstack/react-virtual 做虚拟滚动。

最想分享的一条经验

深色主题的核心不是"把颜色改深"，而是"建立层次感"。

很多开发者做深色主题就是简单地把白色背景改成黑色，结果页面看起来像一个"黑洞"——所有元素都沉在同一个平面上，没有焦点。真正好看的深色主题，靠的是：

1. 背景分层：页面背景最深，卡片背景稍浅，输入框/表格再浅一层
2. 边框和发光：用半透明边框和微弱的外发光区分卡片边界
3. 文字层级：标题用 slate-200，正文用 slate-400，辅助文字用 slate-500/slate-600，靠亮度差建立信息层级
4. 色彩点缀：大面积深色中用少量饱和色（绿/黄/红）做状态标识，形成视觉焦点

这套思路不仅适用于监控仪表盘，适用于所有深色主题的产品设计。