356 lines
12 KiB
Markdown
356 lines
12 KiB
Markdown
# 组件文档目录
|
||
|
||
## 概述
|
||
|
||
本目录包含 Nex Design 系统所有主要组件的详细文档，包括组件说明、参数配置、使用示例等。
|
||
|
||
## 组件列表
|
||
|
||
### 页面布局组件
|
||
|
||
1. **PageTitleBar** - 页面标题栏组件
|
||
- 显示页面标题、描述和操作按钮
|
||
- 支持展开/收起功能
|
||
- 适用于所有页面的顶部区域
|
||
|
||
### 布局容器组件
|
||
|
||
2. **SplitLayout** - 主内容区布局容器
|
||
- 支持横向（左右）和纵向（上下）分栏
|
||
- 主内容区 + 扩展信息区
|
||
- 响应式设计
|
||
|
||
3. **ExtendInfoPanel** - 扩展信息面板
|
||
- 多个可折叠的信息区块
|
||
- 支持垂直堆叠和水平排列
|
||
- 配合 SplitLayout 使用
|
||
|
||
### 列表相关组件
|
||
|
||
4. **ListActionBar** - 列表操作栏组件
|
||
- 提供操作按钮、搜索、筛选功能
|
||
- 适用于列表页面的顶部操作区
|
||
|
||
5. **TreeFilterPanel** - 树形筛选面板组件
|
||
- 树形结构的数据筛选
|
||
- 支持搜索和多级展开
|
||
- 配合 ListActionBar 使用
|
||
|
||
6. **ListTable** - 列表表格组件
|
||
- 统一的表格样式和交互
|
||
- 支持行选择、分页、排序
|
||
- 适用于所有列表页面
|
||
|
||
### 详情展示组件
|
||
|
||
7. **DetailDrawer** - 详情抽屉组件
|
||
- 从右侧滑出的详情面板
|
||
- 支持标签页和操作按钮
|
||
- 固定头部，内容可滚动
|
||
|
||
8. **InfoPanel** - 信息展示面板组件
|
||
- 网格布局展示结构化数据
|
||
- 支持自定义字段渲染
|
||
- 配合 DetailDrawer 使用
|
||
|
||
### 数据展示组件
|
||
|
||
9. **StatCard** - 统计卡片组件
|
||
- 展示数值型统计数据
|
||
- 支持图标、颜色主题、趋势指示器
|
||
- 支持网格布局（单列/双列）
|
||
- 配合 ExtendInfoPanel 使用
|
||
|
||
10. **ChartPanel** - 图表面板组件
|
||
- 基于 ECharts 的图表展示
|
||
- 支持折线图、柱状图、饼图、环形图
|
||
- 自适应容器尺寸
|
||
- 配合 ExtendInfoPanel 使用
|
||
|
||
### 交互反馈组件
|
||
|
||
11. **ConfirmDialog** - 确认对话框组件
|
||
- 提供统一的确认对话框样式
|
||
- 支持删除、警告、通用确认等场景
|
||
- 支持异步操作
|
||
|
||
12. **Toast** - 通知反馈组件
|
||
- 操作完成后的提示信息
|
||
- 支持成功、错误、警告、信息四种类型
|
||
- 从右上角滑出，自动消失
|
||
|
||
## 组件关系图
|
||
|
||
### 页面布局结构
|
||
|
||
#### 横向布局（左右分栏）
|
||
|
||
适用场景：需要持续展示扩展信息的页面（如监控页面、数据分析页面）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ PageTitleBar (页面标题栏) │
|
||
├─────────────────────────────────┬───────────────────────┤
|
||
│ │ │
|
||
│ 主内容区 (Main Content) │ 扩展信息区 │
|
||
│ │ (Extend Info) │
|
||
│ ┌───────────────────────────┐ │ ┌─────────────────┐ │
|
||
│ │ ListActionBar (操作栏) │ │ │ ExtendInfoPanel │ │
|
||
│ │ ├─ 操作按钮 │ │ │ │ │
|
||
│ │ ├─ 搜索框 │ │ │ - 概览区块 │ │
|
||
│ │ └─ TreeFilterPanel │ │ │ - 图表区块 │ │
|
||
│ ├───────────────────────────┤ │ │ - 监控区块 │ │
|
||
│ │ ListTable (数据表格) │ │ │ │ │
|
||
│ │ └─ 点击行 → DetailDrawer │ │ │ (StatCard + │ │
|
||
│ └───────────────────────────┘ │ │ ChartPanel) │ │
|
||
│ │ └─────────────────┘ │
|
||
│ SplitLayout (direction="horizontal") │
|
||
└─────────────────────────────────┴───────────────────────┘
|
||
```
|
||
|
||
#### 纵向布局（上下分栏）
|
||
|
||
适用场景：需要可展开/收起的统计面板（如用户列表、主机列表）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ PageTitleBar (页面标题栏 + Toggle 控制) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 扩展信息区 (Extend Info - 可展开/收起) │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ ExtendInfoPanel (layout="horizontal") │ │
|
||
│ │ │ │
|
||
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
|
||
│ │ │ 总数 │ │ 在线 │ │ 离线 │ │ 筛选 │ │ │
|
||
│ │ │ Card │ │ Card │ │ Card │ │ Card │ │ │
|
||
│ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │
|
||
│ │ (StatCard 组件，水平排列) │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 主内容区 (Main Content) │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ ListActionBar (操作栏) │ │
|
||
│ │ ├─ 操作按钮 │ │
|
||
│ │ ├─ 搜索框 │ │
|
||
│ │ └─ TreeFilterPanel (高级筛选) │ │
|
||
│ ├─────────────────────────────────────────────────┤ │
|
||
│ │ ListTable (数据表格) │ │
|
||
│ │ └─ 点击行 → DetailDrawer │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ SplitLayout (direction="vertical", extendPosition="top") │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
详情抽屉 (从右侧滑出):
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ DetailDrawer │
|
||
│ ├─ InfoPanel (基本信息) │
|
||
│ └─ Tabs (关联数据标签页) │
|
||
└─────────────────────────────────┘
|
||
|
||
交互反馈流程:
|
||
操作 → ConfirmDialog (确认) → Toast (结果反馈)
|
||
```
|
||
|
||
### 组件依赖关系
|
||
|
||
```
|
||
PageTitleBar (独立使用)
|
||
|
||
SplitLayout (布局容器)
|
||
├─ mainContent
|
||
│ ├─ ListActionBar
|
||
│ │ └─ TreeFilterPanel
|
||
│ └─ ListTable
|
||
│ └─ DetailDrawer
|
||
│ └─ InfoPanel
|
||
└─ extendContent
|
||
└─ ExtendInfoPanel
|
||
├─ StatCard
|
||
└─ ChartPanel
|
||
|
||
ConfirmDialog (全局调用)
|
||
Toast (全局调用)
|
||
```
|
||
|
||
## 典型页面组合
|
||
|
||
### 1. 标准列表页面（横向布局）
|
||
|
||
```jsx
|
||
<PageTitleBar title="虚拟机镜像" description="..." />
|
||
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
mainContent={
|
||
<>
|
||
<ListActionBar
|
||
actions={[...]}
|
||
search={{...}}
|
||
/>
|
||
<ListTable
|
||
columns={columns}
|
||
dataSource={data}
|
||
onRowClick={showDetail}
|
||
/>
|
||
</>
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
sections={[
|
||
{
|
||
key: 'overview',
|
||
title: '概览',
|
||
content: <StatCards />
|
||
},
|
||
{
|
||
key: 'monitor',
|
||
title: '性能监控',
|
||
content: <Charts />
|
||
}
|
||
]}
|
||
/>
|
||
}
|
||
/>
|
||
|
||
<DetailDrawer visible={showDrawer}>
|
||
<InfoPanel data={selectedItem} fields={fields} />
|
||
</DetailDrawer>
|
||
```
|
||
|
||
### 2. 带统计面板的列表页面（纵向布局）
|
||
|
||
```jsx
|
||
<PageTitleBar
|
||
title="用户列表"
|
||
showToggle={true}
|
||
onToggle={setShowStats}
|
||
/>
|
||
|
||
<SplitLayout
|
||
direction="vertical"
|
||
mainContent={
|
||
<>
|
||
<ListActionBar
|
||
actions={[...]}
|
||
search={{...}}
|
||
filter={{
|
||
content: <TreeFilterPanel {...} />
|
||
}}
|
||
/>
|
||
<ListTable
|
||
columns={columns}
|
||
dataSource={data}
|
||
/>
|
||
</>
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
layout="horizontal"
|
||
sections={[
|
||
{
|
||
key: 'stats',
|
||
title: '数据统计',
|
||
content: <StatCards />
|
||
}
|
||
]}
|
||
/>
|
||
}
|
||
showExtend={showStats}
|
||
/>
|
||
```
|
||
|
||
### 3. 删除操作流程
|
||
|
||
```jsx
|
||
// 1. 点击删除按钮
|
||
<Button onClick={() => handleDelete(record)}>删除</Button>
|
||
|
||
// 2. 显示确认对话框
|
||
ConfirmDialog.delete({
|
||
itemName: record.name,
|
||
onOk: async () => {
|
||
// 3. 执行删除
|
||
await api.delete(record.id)
|
||
// 4. 显示结果反馈
|
||
Toast.success('删除成功')
|
||
}
|
||
})
|
||
```
|
||
|
||
## 组件选择指南
|
||
|
||
### 布局组件
|
||
|
||
| 场景 | 推荐组件 | 说明 |
|
||
|------|---------|------|
|
||
| 需要右侧信息面板 | SplitLayout (horizontal) + ExtendInfoPanel | 监控页面、数据分析页面 |
|
||
| 需要顶部统计面板 | SplitLayout (vertical) + ExtendInfoPanel | 可展开的统计信息 |
|
||
| 简单列表页 | ListActionBar + ListTable | 无扩展信息需求 |
|
||
|
||
### 数据展示组件
|
||
|
||
| 数据类型 | 推荐组件 | 说明 |
|
||
|---------|---------|------|
|
||
| 统计数值 | StatCard | 简洁的数值展示 |
|
||
| 趋势图表 | ChartPanel (line) | 时间序列数据 |
|
||
| 分布数据 | ChartPanel (pie/ring) | 占比分析 |
|
||
| 对比数据 | ChartPanel (bar) | 类别对比 |
|
||
| 结构化信息 | InfoPanel | 对象详细属性 |
|
||
|
||
### 交互组件
|
||
|
||
| 场景 | 推荐组件 | 说明 |
|
||
|------|---------|------|
|
||
| 危险操作确认 | ConfirmDialog.delete | 删除确认 |
|
||
| 一般操作确认 | ConfirmDialog.confirm | 普通确认 |
|
||
| 操作结果反馈 | Toast | 成功/失败提示 |
|
||
| 筛选数据 | TreeFilterPanel | 树形结构筛选 |
|
||
|
||
## 使用指南
|
||
|
||
### 开始使用
|
||
|
||
1. 从左侧菜单选择组件查看详细文档
|
||
2. 了解组件的参数配置和使用场景
|
||
3. 参考示例代码进行开发
|
||
4. 根据实际需求调整参数
|
||
|
||
### 设计原则
|
||
|
||
- **一致性** - 所有组件使用统一的设计语言
|
||
- **可复用** - 组件高度封装，易于复用
|
||
- **可配置** - 提供丰富的配置选项
|
||
- **易用性** - API 设计简洁直观
|
||
- **响应式** - 自适应不同屏幕尺寸
|
||
|
||
### 技术栈
|
||
|
||
- React 18
|
||
- Ant Design 5.x
|
||
- ECharts 5.x
|
||
- CSS Modules
|
||
|
||
### 命名规范
|
||
|
||
- **组件名**：PascalCase（如 PageTitleBar）
|
||
- **参数名**：camelCase（如 showToggle）
|
||
- **CSS 类名**：kebab-case（如 page-title-bar）
|
||
- **文件名**：与组件名一致（如 PageTitleBar.jsx）
|
||
|
||
## 更新记录
|
||
|
||
- 2025-11-13: 新增布局系统（SplitLayout + ExtendInfoPanel）
|
||
- 2025-11-13: 新增数据展示组件（StatCard + ChartPanel）
|
||
- 2025-11-04: 初始版本，包含 8 个核心组件文档
|
||
|
||
## 相关文档
|
||
|
||
- **主内容区布局** - 详细的布局使用指南
|
||
- **设计手册** - 设计规范和最佳实践
|