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 | 禁用、离线、未激活 |

## 使用示例

### 基础用法

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

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

### 带颜色主题

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

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

### 带趋势指示

```jsx
<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"
/>
```

### 自定义颜色

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

### 布局模式

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

#### 一列布局（默认）

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

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

#### 两列布局

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

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

#### 布局模式选择建议

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

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

### 网格布局

```jsx
<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 使用

```jsx
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` - 下降趋势

### 自定义样式示例

```css
/* 修改卡片圆角 */
.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** - 图表面板（配合使用）