12 KiB
12 KiB
组件文档目录
概述
本目录包含 Nex Design 系统所有主要组件的详细文档，包括组件说明、参数配置、使用示例等。
组件列表
页面布局组件
- PageTitleBar - 页面标题栏组件
- 显示页面标题、描述和操作按钮
- 支持展开/收起功能
- 适用于所有页面的顶部区域
布局容器组件
-
SplitLayout - 主内容区布局容器
- 支持横向（左右）和纵向（上下）分栏
- 主内容区 + 扩展信息区
- 响应式设计
-
ExtendInfoPanel - 扩展信息面板
- 多个可折叠的信息区块
- 支持垂直堆叠和水平排列
- 配合 SplitLayout 使用
列表相关组件
-
ListActionBar - 列表操作栏组件
- 提供操作按钮、搜索、筛选功能
- 适用于列表页面的顶部操作区
-
TreeFilterPanel - 树形筛选面板组件
- 树形结构的数据筛选
- 支持搜索和多级展开
- 配合 ListActionBar 使用
-
ListTable - 列表表格组件
- 统一的表格样式和交互
- 支持行选择、分页、排序
- 适用于所有列表页面
详情展示组件
-
DetailDrawer - 详情抽屉组件
- 从右侧滑出的详情面板
- 支持标签页和操作按钮
- 固定头部，内容可滚动
-
InfoPanel - 信息展示面板组件
- 网格布局展示结构化数据
- 支持自定义字段渲染
- 配合 DetailDrawer 使用
数据展示组件
-
StatCard - 统计卡片组件
- 展示数值型统计数据
- 支持图标、颜色主题、趋势指示器
- 支持网格布局（单列/双列）
- 配合 ExtendInfoPanel 使用
-
ChartPanel - 图表面板组件
- 基于 ECharts 的图表展示
- 支持折线图、柱状图、饼图、环形图
- 自适应容器尺寸
- 配合 ExtendInfoPanel 使用
交互反馈组件
-
ConfirmDialog - 确认对话框组件
- 提供统一的确认对话框样式
- 支持删除、警告、通用确认等场景
- 支持异步操作
-
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 | 树形结构筛选 |
使用指南
开始使用
- 从左侧菜单选择组件查看详细文档
- 了解组件的参数配置和使用场景
- 参考示例代码进行开发
- 根据实际需求调整参数
设计原则
- 一致性 - 所有组件使用统一的设计语言
- 可复用 - 组件高度封装，易于复用
- 可配置 - 提供丰富的配置选项
- 易用性 - 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 个核心组件文档
相关文档
- 主内容区布局 - 详细的布局使用指南
- 设计手册 - 设计规范和最佳实践