nex_design/docs/components

组件文档目录

概述

本目录包含 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. 标准列表页面（横向布局）

<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. 带统计面板的列表页面（纵向布局）

<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. 删除操作流程

// 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 个核心组件文档

相关文档

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