nex_design/docs/components/StatCard.md

StatCard 组件

组件说明

统计卡片组件，用于展示数值型统计数据。支持图标、颜色主题、趋势指示器等功能，适合在仪表盘或信息面板中使用。

组件位置

src/components/StatCard/StatCard.jsx
src/components/StatCard/StatCard.css

参数说明

参数名	类型	必填	默认值	说明
title	string	是	-	卡片标题
value	number | string	是	-	统计值
icon	ReactNode	否	-	图标
color	string	否	'blue'	主题颜色：blue/green/orange/red/purple/gray 或自定义颜色值
trend	TrendConfig	否	-	趋势信息
suffix	string	否	''	后缀单位
layout	string	否	'column'	布局模式：'column'（一列）| 'row'（两列）
className	string	否	''	自定义类名

TrendConfig 配置项

属性名	类型	必填	说明
value	number	是	趋势值（百分比，自动取绝对值）
direction	'up' | 'down'	是	趋势方向

颜色预设

颜色名	色值	适用场景
blue	#1677ff	默认、总数、常规数据
green	#52c41a	成功、在线、正常状态
orange	#faad14	警告、待处理
red	#ff4d4f	错误、危险、异常
purple	#722ed1	特殊、高级功能
gray	#8c8c8c	禁用、离线、未激活

使用示例

基础用法

import StatCard from '../components/StatCard/StatCard'
import { DatabaseOutlined } from '@ant-design/icons'

<StatCard
  title="镜像总数"
  value={32}
  icon={<DatabaseOutlined />}
/>

带颜色主题

<StatCard
  title="在线用户"
  value={156}
  icon={<UserOutlined />}
  color="green"
/>

<StatCard
  title="错误数量"
  value={3}
  icon={<CloseCircleOutlined />}
  color="red"
/>

带趋势指示

<StatCard
  title="访问量"
  value={1250}
  icon={<LineChartOutlined />}
  trend={{ value: 12.5, direction: 'up' }}
/>

<StatCard
  title="响应时间"
  value={245}
  suffix="ms"
  trend={{ value: 8.3, direction: 'down' }}
  color="green"
/>

自定义颜色

<StatCard
  title="自定义指标"
  value={88}
  color="#9c27b0"
  suffix="%"
/>

布局模式

StatCard 支持两种布局模式，通过 layout 参数配置：

一列布局（默认）

标题和图标在上方，数值和趋势在下方。适合垂直排列的卡片网格。

<StatCard
  title="CPU使用率"
  value={45}
  suffix="%"
  icon={<DashboardOutlined />}
  color="blue"
  trend={{ value: 5, direction: 'up' }}
/>

两列布局

左侧显示标题和图标，右侧显示数值和趋势。适合在较宽的容器中横向展示数据。

<StatCard
  layout="row"
  title="内存使用率"
  value={62}
  suffix="%"
  icon={<DatabaseOutlined />}
  color="orange"
  trend={{ value: 3, direction: 'down' }}
/>

布局模式选择建议

• 一列布局（column）：

  • 适用于窄宽度容器（如侧边信息面板）
  • 适用于网格布局中垂直排列
  • 数值作为视觉焦点，强调数据本身

• 两列布局（row）：

  • 适用于较宽的容器（宽度 > 300px）
  • 适用于列表或卡片中横向展示
  • 平衡展示标题和数值，节省垂直空间

网格布局

<div style={{ display: 'grid', gap: '12px' }}>
  <StatCard
    title="总数"
    value={100}
    icon={<DatabaseOutlined />}
    color="blue"
  />
  <StatCard
    title="在线"
    value={85}
    icon={<CheckCircleOutlined />}
    color="green"
    trend={{ value: 12, direction: 'up' }}
  />
  <StatCard
    title="离线"
    value={15}
    icon={<CloseCircleOutlined />}
    color="gray"
  />
</div>

配合 SideInfoPanel 使用

import SideInfoPanel from '../components/SideInfoPanel/SideInfoPanel'
import StatCard from '../components/StatCard/StatCard'

<SideInfoPanel
  sections={[
    {
      key: 'overview',
      title: '系统概览',
      content: (
        <div style={{ display: 'grid', gap: '12px' }}>
          <StatCard
            title="CPU使用率"
            value={45}
            suffix="%"
            icon={<DashboardOutlined />}
            trend={{ value: 5, direction: 'up' }}
          />
          <StatCard
            title="内存使用率"
            value={62}
            suffix="%"
            color="orange"
            trend={{ value: 3, direction: 'down' }}
          />
          <StatCard
            title="磁盘使用率"
            value={78}
            suffix="%"
            color="red"
          />
        </div>
      ),
    },
  ]}
/>

样式定制

组件提供以下 CSS 类名供自定义样式：

• .stat-card - 卡片容器
• .stat-card-column - 一列布局模式
• .stat-card-row - 两列布局模式
• .stat-card-header - 卡片头部
• .stat-card-title - 标题文本
• .stat-card-icon - 图标
• .stat-card-body - 卡片内容
• .stat-card-value - 统计值
• .stat-card-suffix - 后缀单位
• .stat-card-trend - 趋势指示器
• .trend-up - 上升趋势
• .trend-down - 下降趋势

自定义样式示例

/* 修改卡片圆角 */
.stat-card {
  border-radius: 12px;
}

/* 自定义标题样式 */
.stat-card-title {
  font-size: 14px;
  font-weight: 600;
}

/* 自定义数值大小 */
.stat-card-value {
  font-size: 28px;
}

使用场景

1. 仪表盘概览 - 展示关键业务指标
2. 系统监控 - 展示CPU、内存、磁盘使用率
3. 数据统计 - 展示用户数、订单数等统计数据
4. 性能指标 - 展示响应时间、吞吐量等性能数据

注意事项

1. 数值格式化：

   • 大数值建议使用千分位格式（如 1,250）
   • 小数建议保留 1-2 位
   • 使用 suffix 添加单位，而不是直接拼接在 value 中

2. 颜色使用：

   • 保持颜色语义一致（绿色=正常，红色=错误）
   • 避免过多颜色，建议同一页面不超过 4 种
   • 优先使用预设颜色，保持风格统一

3. 趋势指示：

   • 趋势值会自动取绝对值显示
   • 上升趋势不一定是好事（如错误率上升）
   • 根据业务含义选择合适的颜色

4. 布局建议：

   • 一列布局（column）：适合侧边信息面板和网格垂直排列
   • 两列布局（row）：适合较宽容器和横向展示
   • 网格布局推荐使用：display: grid; gap: 12px;
   • 避免卡片过宽，建议最大宽度 400px
   • 根据容器宽度选择合适的 layout 模式

5. 图标选择：

   • 使用与数据相关的图标
   • 保持图标风格统一
   • 避免过于复杂的图标

配合使用的组件

• SideInfoPanel - 侧边信息面板（推荐）
• SplitLayout - 分栏布局
• ChartPanel - 图表面板（配合使用）