nex_design/docs/components/README.md

# 组件文档目录

## 概述

本目录包含 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 个核心组件文档

## 相关文档

- **主内容区布局** - 详细的布局使用指南
- **设计手册** - 设计规范和最佳实践