299 lines
6.8 KiB
Markdown
299 lines
6.8 KiB
Markdown
# 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** - 图表面板（配合使用）
|