348 lines
9.5 KiB
Markdown
348 lines
9.5 KiB
Markdown
# 主内容区布局
|
||
|
||
## 概述
|
||
|
||
主内容区布局是页面中除了导航栏外的核心内容区域，由 **SplitLayout** 和 **ExtendInfoPanel** 两个核心组件组成，提供灵活的横向（左右）和纵向（上下）分栏布局方案。
|
||
|
||
## 布局模式
|
||
|
||
### 1. 横向布局（Horizontal）
|
||
|
||
**适用场景**：需要在主内容区右侧展示扩展信息的页面
|
||
|
||
**布局结构**：
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ PageTitleBar │
|
||
├──────────────────────────┬──────────────┤
|
||
│ │ │
|
||
│ Main Content │ Extend │
|
||
│ - ListActionBar │ Info │
|
||
│ - ListTable │ Panel │
|
||
│ │ │
|
||
└──────────────────────────┴──────────────┘
|
||
```
|
||
|
||
**代码示例**：
|
||
```jsx
|
||
import SplitLayout from '../components/SplitLayout/SplitLayout'
|
||
import ExtendInfoPanel from '../components/ExtendInfoPanel/ExtendInfoPanel'
|
||
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
mainContent={
|
||
<>
|
||
<ListActionBar ... />
|
||
<ListTable ... />
|
||
</>
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
sections={[
|
||
{
|
||
key: 'overview',
|
||
title: '概览',
|
||
icon: <DashboardOutlined />,
|
||
content: <StatCards />
|
||
},
|
||
{
|
||
key: 'charts',
|
||
title: '图表',
|
||
content: <Charts />
|
||
}
|
||
]}
|
||
/>
|
||
}
|
||
extendSize={360}
|
||
extendPosition="right"
|
||
/>
|
||
```
|
||
|
||
### 2. 纵向布局（Vertical）
|
||
|
||
**适用场景**：需要在主内容区顶部展示统计信息或扩展面板的页面
|
||
|
||
**布局结构**：
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ PageTitleBar (带展开/收起按钮) │
|
||
├─────────────────────────────────────────┤
|
||
│ Extend Info Panel (可收起) │
|
||
│ - 统计卡片 / 图表 / 其他扩展信息 │
|
||
├─────────────────────────────────────────┤
|
||
│ Main Content │
|
||
│ - ListActionBar │
|
||
│ - ListTable │
|
||
│ │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**代码示例**：
|
||
```jsx
|
||
import { useState } from 'react'
|
||
import SplitLayout from '../components/SplitLayout/SplitLayout'
|
||
import ExtendInfoPanel from '../components/ExtendInfoPanel/ExtendInfoPanel'
|
||
|
||
function MyPage() {
|
||
const [showExtend, setShowExtend] = useState(false)
|
||
|
||
return (
|
||
<>
|
||
<PageTitleBar
|
||
title="页面标题"
|
||
showToggle={true}
|
||
defaultExpanded={false}
|
||
onToggle={setShowExtend}
|
||
/>
|
||
|
||
<SplitLayout
|
||
direction="vertical"
|
||
mainContent={
|
||
<>
|
||
<ListActionBar ... />
|
||
<ListTable ... />
|
||
</>
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
layout="horizontal"
|
||
sections={[
|
||
{
|
||
key: 'stats',
|
||
title: '数据统计',
|
||
content: (
|
||
<div style={{ display: 'flex', gap: '16px' }}>
|
||
<StatCard title="总数" value={100} />
|
||
<StatCard title="在线" value={80} />
|
||
</div>
|
||
)
|
||
}
|
||
]}
|
||
/>
|
||
}
|
||
showExtend={showExtend}
|
||
extendPosition="top"
|
||
/>
|
||
</>
|
||
)
|
||
}
|
||
```
|
||
|
||
## 核心组件
|
||
|
||
### SplitLayout
|
||
|
||
**职责**：主内容区的布局容器，支持横向和纵向分栏
|
||
|
||
**参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| direction | string | 否 | 'horizontal' | 布局方向：'horizontal'（左右）\| 'vertical'（上下） |
|
||
| mainContent | ReactNode | 是 | - | 主内容区 |
|
||
| extendContent | ReactNode | 否 | - | 扩展内容区 |
|
||
| extendSize | number | 否 | 360 | 扩展区尺寸（horizontal 模式下为宽度，px） |
|
||
| gap | number | 否 | 16 | 主内容与扩展区间距（px） |
|
||
| showExtend | boolean | 否 | true | 是否显示扩展区 |
|
||
| extendPosition | string | 否 | 'right'/'top' | 扩展区位置：horizontal 模式下为 'right'，vertical 模式下为 'top' |
|
||
| className | string | 否 | '' | 自定义类名 |
|
||
|
||
**详细文档**：[SplitLayout.md](../components/SplitLayout.md)
|
||
|
||
### ExtendInfoPanel
|
||
|
||
**职责**：扩展信息面板容器，支持多个可折叠区块
|
||
|
||
**参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| sections | Array | 是 | [] | 区块配置数组 |
|
||
| layout | string | 否 | 'vertical' | 布局方式：'vertical'（垂直堆叠）\| 'horizontal'（水平排列） |
|
||
| className | string | 否 | '' | 自定义类名 |
|
||
|
||
**Section 配置项**：
|
||
|
||
| 属性名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| key | string | 是 | 区块唯一标识 |
|
||
| title | string | 是 | 区块标题 |
|
||
| icon | ReactNode | 否 | 标题图标 |
|
||
| content | ReactNode | 是 | 区块内容 |
|
||
| defaultCollapsed | boolean | 否 | 默认是否折叠 |
|
||
|
||
**详细文档**：[ExtendInfoPanel.md](../components/ExtendInfoPanel.md)
|
||
|
||
## 使用场景
|
||
|
||
### 场景 1：带右侧信息面板的列表页
|
||
|
||
**示例页面**：虚拟机镜像管理页（VirtualMachineImagePage）
|
||
|
||
**特点**：
|
||
- 左侧：操作栏 + 数据表格
|
||
- 右侧：概览统计 + 图表监控
|
||
|
||
**布局选择**：横向布局（horizontal）
|
||
|
||
### 场景 2：带顶部统计面板的列表页
|
||
|
||
**示例页面**：用户列表页（UserListPage）
|
||
|
||
**特点**：
|
||
- 顶部：可展开/收起的统计面板
|
||
- 下方：操作栏 + 数据表格
|
||
|
||
**布局选择**：纵向布局（vertical）
|
||
|
||
### 场景 3：纯表格列表页
|
||
|
||
**示例页面**：简单的数据列表页
|
||
|
||
**特点**：
|
||
- 只有操作栏和数据表格
|
||
- 无扩展信息区
|
||
|
||
**布局选择**：直接使用 ListActionBar + ListTable，不使用 SplitLayout
|
||
|
||
```jsx
|
||
<>
|
||
<PageTitleBar title="简单列表" />
|
||
<ListActionBar ... />
|
||
<ListTable ... />
|
||
</>
|
||
```
|
||
|
||
## 布局对比
|
||
|
||
| 特性 | 横向布局 | 纵向布局 | 无布局 |
|
||
|------|---------|---------|--------|
|
||
| 扩展区位置 | 右侧 | 顶部 | 无 |
|
||
| 扩展区尺寸 | 固定宽度 | 高度自适应 | - |
|
||
| 主内容宽度 | 自适应 | 100% | 100% |
|
||
| 展开/收起 | 响应式隐藏 | PageTitleBar 控制 | - |
|
||
| 适用场景 | 仪表盘、监控页 | 统计分析页 | 简单列表页 |
|
||
|
||
## 响应式设计
|
||
|
||
### 横向布局响应式
|
||
|
||
- **宽屏（> 1200px）**：显示扩展信息区
|
||
- **中等屏幕（≤ 1200px）**：自动隐藏扩展信息区，主内容占满
|
||
|
||
```css
|
||
@media (max-width: 1200px) {
|
||
.split-layout-extend-right {
|
||
display: none;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 纵向布局响应式
|
||
|
||
- 扩展区始终占满宽度
|
||
- 通过 `showExtend` 参数控制显示/隐藏
|
||
- 建议配合 PageTitleBar 的 toggle 功能使用
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 选择合适的布局模式
|
||
|
||
```jsx
|
||
// ✅ 好的做法：监控页面使用横向布局
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
extendSize={360}
|
||
mainContent={<MonitorTable />}
|
||
extendContent={<RealTimeCharts />}
|
||
/>
|
||
|
||
// ✅ 好的做法：统计页面使用纵向布局
|
||
<SplitLayout
|
||
direction="vertical"
|
||
mainContent={<UserTable />}
|
||
extendContent={<StatsPanel />}
|
||
showExtend={showStats}
|
||
/>
|
||
|
||
// ❌ 避免：简单列表页使用复杂布局
|
||
// 直接使用 ListActionBar + ListTable 即可
|
||
```
|
||
|
||
### 2. ExtendInfoPanel 的 layout 选择
|
||
|
||
```jsx
|
||
// horizontal 方向的 SplitLayout 配合 vertical layout 的 ExtendInfoPanel
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
layout="vertical" // 区块垂直堆叠
|
||
sections={[...]}
|
||
/>
|
||
}
|
||
/>
|
||
|
||
// vertical 方向的 SplitLayout 配合 horizontal layout 的 ExtendInfoPanel
|
||
<SplitLayout
|
||
direction="vertical"
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
layout="horizontal" // 区块水平排列
|
||
sections={[...]}
|
||
/>
|
||
}
|
||
/>
|
||
```
|
||
|
||
### 3. 合理设置扩展区尺寸
|
||
|
||
```jsx
|
||
// ✅ 横向布局：扩展区宽度推荐 320-400px
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
extendSize={360}
|
||
/>
|
||
|
||
// ✅ 纵向布局：高度自适应，由内容决定
|
||
<SplitLayout
|
||
direction="vertical"
|
||
// 不需要设置 extendSize
|
||
/>
|
||
```
|
||
|
||
### 4. 统一命名规范
|
||
|
||
```jsx
|
||
// ✅ 使用新的参数命名
|
||
<SplitLayout
|
||
mainContent={...} // 主内容
|
||
extendContent={...} // 扩展内容
|
||
showExtend={...} // 显示扩展区
|
||
extendSize={...} // 扩展区尺寸
|
||
extendPosition={...} // 扩展区位置
|
||
/>
|
||
|
||
// ❌ 避免使用旧的命名（已废弃）
|
||
<SplitLayout
|
||
leftContent={...}
|
||
rightContent={...}
|
||
showRight={...}
|
||
rightWidth={...}
|
||
/>
|
||
```
|
||
|
||
## 相关组件
|
||
|
||
- [PageTitleBar](../components/PageTitleBar.md) - 页面标题栏
|
||
- [ListActionBar](../components/ListActionBar.md) - 列表操作栏
|
||
- [ListTable](../components/ListTable.md) - 列表表格
|
||
- [StatCard](../components/StatCard.md) - 统计卡片
|
||
- [ChartPanel](../components/ChartPanel.md) - 图表面板
|
||
- [InfoPanel](../components/InfoPanel.md) - 信息展示面板
|
||
|
||
## 示例页面
|
||
|
||
- **横向布局示例**：`src/pages/VirtualMachineImagePage.jsx`
|
||
- **纵向布局示例**：`src/pages/UserListPage.jsx`
|