---
title: 设计文档
order: 2
category: atom
---

# 资源链接

## 任务链接

&#x20;

## Figma链接

https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=2192-429

# 1. 组件概述

| **组件名称（英文）**                                                                                 | Metric Card                                                                                                 |
|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| **组件编号**                                                                                     | pcp\_dd\_metricCard\_V1.0                                                                                   |
| **组件类型**                                                                                     | Pro Components                                                                                              |
| **组件分类**                                                                                     | Data Display                                                                                                |
| **<span style="color: rgb(216,57,49); background-color: rgba(254,212,164,0.8)">依赖组件</span>** | 基于[ Base Card](https://m1ed09stz4r.feishu.cn/wiki/A0MHwnavCi3CSek3nX6c3Uw2nCb)封装，在Base Card的基础上确定了内容以及展示的样式 |
| **简介**                                                                                       | 项目统计卡片组件用于在看板、项目概览、业务总览等场景中， 高密度、结构化地展示单一核心指标，并可辅以趋势变化、对比说明、子指标拆分及轻量可视化图表。                                  |

# 2. 版本

| **版本**   | 1.0  |
|----------|------|
| **更新简介** | 首次发布 |

# 3. 组件设计目的

* **统一指标表达方式**：避免不同页面中 KPI/统计卡片样式与语义不一致

* **提升组件复用性**：一套组件覆盖概览、详情、对比等多种场景

* **支持多信息密度**：从极简数值到富信息卡片均可配置

* **适配多端**：PC/ Mobile /Pad / Kiosk 使用同一组件模型

* **支撑低代码/无代码**：不同层级人员均可操作配置项

# 4. 适用场景

| **场景**   | 示例            |
|----------|---------------|
| **数据看板** | 项目评分、活跃用户数、收入 |
| **项目概览** | 当前项目完成率、健康度   |
| **运营分析** | 环比 / 同比指标展示   |
| **管理后台** | 商家核心经营指标      |

# 5. UI 设计

## 5.1 展示样式

### 5.1.1 基础结构

```
┌─────────────────────────────────┐
│  Title                          │  ← 标题（必填）
│  Subtitle                       │  ← 副标题（可选）
│                                 │
│  1,234                          │  ← 主数值（大字号，支持格式化）
│                                 │
│  v.s. pre +12 ↑                │  ← 环比信息 + 趋势箭头（可选）
│  🏷️ Tag                        │  ← 标签（可选）
└─────────────────────────────────┘
```

### 5.1.2 参考设计

![设计示例](https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=2196-1980&m=dev)

实际效果参考截图：

- Total Orders: 50，v.s. pre +12 ↑
- Total Sales: $1580，v.s. pre +$120 ↑
- Total Discount: $230，v.s. pre +$80 ↑
- Total Items: 3249，v.s. pre -230 ↓
- Refunded: 12，v.s. pre +12 ↑

### 5.1.3 状态变体

- **默认态**：显示标题 + 数值
- **完整态**：标题 + 副标题 + 数值 + 环比 + 趋势箭头 + 标签 + 提示

## 5.2 **视觉设计规范**

### 5.2.1 颜色规范

| 元素       | 颜色值                   | 说明     |
|----------|-----------------------|--------|
| 标题       | `rgba(0, 0, 0, 0.45)` | 次要文本色  |
| 副标题      | `rgba(0, 0, 0, 0.45)` | 次要文本色  |
| 主数值      | `rgba(0, 0, 0, 0.85)` | 主要文本色  |
| 环比文本（正）  | `#52c41a`（绿色）         | 正向趋势   |
| 环比文本（负）  | `#ff4d4f`（红色）         | 负向趋势   |
| 趋势箭头（上升） | `#52c41a`（绿色）         | 对应正值   |
| 趋势箭头（下降） | `#ff4d4f`（红色）         | 对应负值   |
| 卡片背景     | `#ffffff`             | 默认白色背景 |
| 卡片边框     | `rgba(0, 0, 0, 0.06)` | 淡灰色边框  |

### 5.2.2 尺寸规范

| 元素   | 字号   | 字重  | 行高   |
|------|------|-----|------|
| 标题   | 14px | 400 | 22px |
| 副标题  | 12px | 400 | 20px |
| 主数值  | 30px | 600 | 38px |
| 环比文本 | 14px | 400 | 22px |
| 标签   | 12px | 400 | 20px |

### 5.2.3 间距规范

| 位置          | 间距   | 说明            |
|-------------|------|---------------|
| 卡片内边距       | 16px | 卡片 padding    |
| 标题与副标题间距    | 4px  | 垂直间距          |
| 副标题与主数值间距   | 8px  | 垂直间距          |
| 主数值与环比信息间距  | 4px  | 垂直间距          |
| 环比文本与趋势箭头间距 | 4px  | 水平间距          |
| 环比信息与标签间距   | 8px  | 垂直间距          |
| 卡片圆角        | 12px | border-radius |

# 6. 配置项

## 6.1 核心数据配置

| 配置项            | 类型                  | 说明             | 默认值        |
|----------------|---------------------|----------------|------------|
| title          | string \| ReactNode | 标题文本           | -          |
| subtitle       | string \| ReactNode | 副标题文本（可选）      | -          |
| value          | number \| string    | 主数值            | -          |
| comparison     | number \| string    | 环比数值（可选，支持正负值） | -          |
| comparisonText | string              | 环比前缀文本         | 'v.s. pre' |
| tag            | ReactNode           | 标签内容（可选）       | -          |
| tooltip        | string \| ReactNode | 提示信息内容（可选）     | -          |

## 6.2 数值格式化配置

| 配置项                        | 类型       | 说明           | 默认值   |
|----------------------------|----------|--------------|-------|
| precision                  | number   | 小数精度（小数位数）   | 0     |
| useGrouping                | boolean  | 是否使用千分位分隔符   | false |
| showCurrencySymbol         | boolean  | 是否显示货币符号     | false |
| currencySymbol             | string   | 货币符号（如 $, ¥） | ''    |
| formatter                  | function | 自定义格式化函数     | -     |
| hideDecimalForWholeNumbers | boolean  | 整数时隐藏小数部分    | true  |

## 6.3 样式自定义配置

### 6.3.1 卡片容器样式

| 配置项          | 类型                | 说明                 | 默认值       |
|--------------|-------------------|--------------------|-----------|
| bordered     | boolean           | 是否显示边框             | true      |
| borderRadius | number            | 圆角大小（px）           | 12        |
| padding      | number            | 内边距（px）            | 16        |
| shadow       | boolean \| string | 阴影效果               | true      |
| background   | string            | 背景色                | '#ffffff' |
| width        | string \| number  | 卡片宽度（支持 auto、100%） | 'auto'    |

### 6.3.2 标题样式

| 配置项         | 类型               | 说明   | 默认值                   |
|-------------|------------------|------|-----------------------|
| titleSize   | number \| string | 标题字号 | 14                    |
| titleWeight | number \| string | 标题字重 | 400                   |
| titleColor  | string           | 标题颜色 | 'rgba(0, 0, 0, 0.45)' |

### 6.3.3 数值样式

| 配置项         | 类型               | 说明   | 默认值                   |
|-------------|------------------|------|-----------------------|
| valueSize   | number \| string | 数值字号 | 30                    |
| valueWeight | number \| string | 数值字重 | 600                   |
| valueColor  | string           | 数值颜色 | 'rgba(0, 0, 0, 0.85)' |

### 6.3.4 环比样式

| 配置项            | 类型               | 说明       | 默认值       |
|----------------|------------------|----------|-----------|
| comparisonSize | number \| string | 环比字号     | 14        |
| positiveColor  | string           | 正向趋势颜色   | '#52c41a' |
| negativeColor  | string           | 负向趋势颜色   | '#ff4d4f' |
| showTrendIcon  | boolean          | 是否显示趋势箭头 | true      |

## 6.4 功能开关配置

| 配置项            | 类型      | 说明          | 默认值   |
|----------------|---------|-------------|-------|
| showSubtitle   | boolean | 是否显示副标题     | false |
| showComparison | boolean | 是否显示环比信息    | false |
| showTrendIcon  | boolean | 是否显示趋势箭头    | true  |
| showTag        | boolean | 是否显示标签      | false |
| showTooltip    | boolean | 是否显示提示信息    | false |
| loading        | boolean | 是否显示加载状态    | false |
| hoverable      | boolean | 鼠标悬停是否有交互效果 | true  |

# 7. 示例

## 7.1 基础示例

```
<PisellMetricCard
  title="Total Orders"
  value={50}
/>
```

效果：

- 显示标题 "Total Orders"
- 显示数值 "50"

## 7.2 完整示例（带环比和趋势）

```
<PisellMetricCard
  title="Total Sales"
  value={1580}
  showCurrencySymbol
  currencySymbol="$"
  comparison={120}
  comparisonText="v.s. pre"
  showComparison
  showTrendIcon
/>
```

效果：

- 显示标题 "Total Sales"
- 显示数值 "$1580"
- 显示环比 "v.s. pre +$120" + 绿色上升箭头

## 7.3 负向趋势示例

```
<PisellMetricCard
  title="Total Items"
  value={3249}
  comparison={-230}
  showComparison
  showTrendIcon
/>
```

效果：

- 显示标题 "Total Items"
- 显示数值 "3249"
- 显示环比 "v.s. pre -230" + 红色下降箭头

## 7.4 带副标题和标签示例```
<PisellMetricCard
  title="Active Users"
  subtitle="Last 30 days"
  value={1128}
  tag={<Tag color="green">+15%</Tag>}
  showTag
  showSubtitle
/>
```

## 7.5 自定义格式化示例

```
<PisellMetricCard
  title="Conversion Rate"
  value={18.5}
  precision={2}
  formatter={(value) => `${value}%`}
/>
```

效果：

- 显示 "18.50%"

## 7.6 千分位格式化示例

```
<PisellMetricCard
  title="Total Revenue"
  value={1234567}
  useGrouping
  showCurrencySymbol
  currencySymbol="$"
  precision={2}
/>
```

效果：

- 显示 "$1,234,567.00"

# 8. 技术实现要点

## 8.1 依赖组件

- **PisellCard**：提供卡片容器基础能力（边框、圆角、阴影、padding 等）
- **Ant Design Statistic**：参考其数值展示和格式化能力
- **Ant Design Tooltip**：提供提示信息功能
- **Ant Design Tag**：提供标签功能

## 8.2 工具函数复用

- `formatNumber`（来自 `@pisell/utils`）：数值格式化
- `formatAmountWithOptions`（来自 `@pisell/utils`）：货币格式化

## 8.3 趋势箭头实现- 使用 Ant Design 图标库：`ArrowUpOutlined`、`ArrowDownOutlined`
- 根据 `comparison` 值自动判断正负
- 正值显示绿色上升箭头，负值显示红色下降箭头## 8.4 响应式设计- 支持移动端、平板、PC 端自适应
- 可根据容器宽度自动调整布局
