448 lines
12 KiB
Markdown
448 lines
12 KiB
Markdown
# SplitLayout 组件
|
||
|
||
## 组件说明
|
||
|
||
主内容区布局组件，支持横向（左右）和纵向（上下）两种分栏模式。用于将页面划分为主内容区和扩展信息区，支持响应式设计和灵活的布局配置。
|
||
|
||
## 组件位置
|
||
|
||
```
|
||
src/components/SplitLayout/SplitLayout.jsx
|
||
src/components/SplitLayout/SplitLayout.css
|
||
```
|
||
|
||
## 参数说明
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| direction | string | 否 | 'horizontal' | 布局方向：'horizontal'（左右分栏）\| 'vertical'（上下分栏） |
|
||
| mainContent | ReactNode | 是 | - | 主内容区 |
|
||
| extendContent | ReactNode | 否 | - | 扩展内容区 |
|
||
| extendSize | number | 否 | 360 | 扩展区尺寸（horizontal 模式下为宽度，px） |
|
||
| gap | number | 否 | 16 | 主内容与扩展区间距（px） |
|
||
| showExtend | boolean | 否 | true | 是否显示扩展区 |
|
||
| extendPosition | string | 否 | 根据 direction 自动设置 | 扩展区位置：horizontal 模式默认 'right'，vertical 模式默认 'top' |
|
||
| className | string | 否 | '' | 自定义类名 |
|
||
|
||
## 布局模式
|
||
|
||
### 横向布局（Horizontal）
|
||
|
||
左右分栏，主内容在左，扩展信息在右。
|
||
|
||
**布局结构**：
|
||
```
|
||
┌──────────────────────────┬──────────────────┐
|
||
│ │ │
|
||
│ Main Content │ Extend Info │
|
||
│ (flex: 1) │ (固定宽度) │
|
||
│ │ (可独立滚动) │
|
||
│ │ │
|
||
└──────────────────────────┴──────────────────┘
|
||
```
|
||
|
||
**适用场景**：
|
||
- 数据列表 + 统计信息面板
|
||
- 监控页面 + 实时数据面板
|
||
- 表单编辑 + 帮助文档
|
||
|
||
### 纵向布局（Vertical）
|
||
|
||
上下分栏，扩展信息在上，主内容在下。
|
||
|
||
**布局结构**：
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Extend Info (高度自适应, 可收起) │
|
||
├─────────────────────────────────────────┤
|
||
│ │
|
||
│ Main Content │
|
||
│ │
|
||
│ │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**适用场景**：
|
||
- 带统计面板的列表页
|
||
- 可展开/收起的筛选条件区
|
||
- 概览信息 + 详细列表
|
||
|
||
## 使用示例
|
||
|
||
### 基础用法 - 横向布局
|
||
|
||
```jsx
|
||
import SplitLayout from '../components/SplitLayout/SplitLayout'
|
||
import ListTable from '../components/ListTable/ListTable'
|
||
import ExtendInfoPanel from '../components/ExtendInfoPanel/ExtendInfoPanel'
|
||
|
||
function MyPage() {
|
||
return (
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
mainContent={
|
||
<ListTable columns={columns} dataSource={data} />
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel sections={sections} />
|
||
}
|
||
/>
|
||
)
|
||
}
|
||
```
|
||
|
||
### 纵向布局 + 可折叠
|
||
|
||
```jsx
|
||
import { useState } from 'react'
|
||
import PageTitleBar from '../components/PageTitleBar/PageTitleBar'
|
||
import SplitLayout from '../components/SplitLayout/SplitLayout'
|
||
import ExtendInfoPanel from '../components/ExtendInfoPanel/ExtendInfoPanel'
|
||
|
||
function MyPage() {
|
||
const [showStats, setShowStats] = useState(false)
|
||
|
||
return (
|
||
<>
|
||
<PageTitleBar
|
||
title="用户列表"
|
||
showToggle={true}
|
||
defaultExpanded={false}
|
||
onToggle={setShowStats}
|
||
/>
|
||
|
||
<SplitLayout
|
||
direction="vertical"
|
||
mainContent={
|
||
<>
|
||
<ListActionBar ... />
|
||
<ListTable ... />
|
||
</>
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
layout="horizontal"
|
||
sections={[
|
||
{
|
||
key: 'stats',
|
||
title: '数据统计',
|
||
content: <StatCards />
|
||
}
|
||
]}
|
||
/>
|
||
}
|
||
showExtend={showStats}
|
||
/>
|
||
</>
|
||
)
|
||
}
|
||
```
|
||
|
||
### 自定义尺寸和间距
|
||
|
||
```jsx
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
mainContent={<div>主内容</div>}
|
||
extendContent={<div>扩展信息</div>}
|
||
extendSize={400}
|
||
gap={24}
|
||
/>
|
||
```
|
||
|
||
### 完整示例 - 虚拟机镜像页面
|
||
|
||
```jsx
|
||
import { useState } from 'react'
|
||
import SplitLayout from '../components/SplitLayout/SplitLayout'
|
||
import ListActionBar from '../components/ListActionBar/ListActionBar'
|
||
import ListTable from '../components/ListTable/ListTable'
|
||
import ExtendInfoPanel from '../components/ExtendInfoPanel/ExtendInfoPanel'
|
||
import StatCard from '../components/StatCard/StatCard'
|
||
import ChartPanel from '../components/ChartPanel/ChartPanel'
|
||
|
||
function VirtualMachineImagePage() {
|
||
const [selectedRowKeys, setSelectedRowKeys] = useState([])
|
||
|
||
return (
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
mainContent={
|
||
<>
|
||
<ListActionBar
|
||
actions={[
|
||
{ key: 'add', label: '新建镜像', type: 'primary' },
|
||
{ key: 'delete', label: '批量删除', danger: true },
|
||
]}
|
||
search={{ placeholder: '搜索镜像' }}
|
||
/>
|
||
<ListTable
|
||
columns={columns}
|
||
dataSource={data}
|
||
selectedRowKeys={selectedRowKeys}
|
||
onSelectionChange={setSelectedRowKeys}
|
||
/>
|
||
</>
|
||
}
|
||
extendContent={
|
||
<ExtendInfoPanel
|
||
sections={[
|
||
{
|
||
key: 'overview',
|
||
title: '概览',
|
||
content: (
|
||
<div style={{ display: 'grid', gap: '12px' }}>
|
||
<StatCard
|
||
key="total"
|
||
title="镜像总数"
|
||
value={32}
|
||
icon={<DatabaseOutlined />}
|
||
color="blue"
|
||
gridColumn="1 / -1"
|
||
/>
|
||
<StatCard
|
||
key="running"
|
||
title="运行中"
|
||
value={28}
|
||
color="green"
|
||
/>
|
||
<StatCard
|
||
key="stopped"
|
||
title="已停止"
|
||
value={4}
|
||
color="gray"
|
||
/>
|
||
</div>
|
||
),
|
||
},
|
||
{
|
||
key: 'charts',
|
||
title: '性能监控',
|
||
content: (
|
||
<>
|
||
<ChartPanel
|
||
type="line"
|
||
title="CPU使用率趋势"
|
||
data={cpuData}
|
||
height={180}
|
||
/>
|
||
<ChartPanel
|
||
type="line"
|
||
title="内存使用率趋势"
|
||
data={memoryData}
|
||
height={180}
|
||
/>
|
||
</>
|
||
),
|
||
},
|
||
]}
|
||
/>
|
||
}
|
||
extendSize={360}
|
||
extendPosition="right"
|
||
/>
|
||
)
|
||
}
|
||
```
|
||
|
||
## DOM 结构
|
||
|
||
### 横向布局
|
||
|
||
```html
|
||
<div class="split-layout split-layout-horizontal" style="gap: 16px">
|
||
<!-- 主内容区 -->
|
||
<div class="split-layout-main">
|
||
{mainContent}
|
||
</div>
|
||
|
||
<!-- 扩展信息区 -->
|
||
<div class="split-layout-extend split-layout-extend-right" style="width: 360px">
|
||
{extendContent}
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
### 纵向布局
|
||
|
||
```html
|
||
<div class="split-layout split-layout-vertical" style="gap: 16px">
|
||
<!-- 扩展信息区 -->
|
||
<div class="split-layout-extend split-layout-extend-top">
|
||
{extendContent}
|
||
</div>
|
||
|
||
<!-- 主内容区 -->
|
||
<div class="split-layout-main">
|
||
{mainContent}
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
## 响应式设计
|
||
|
||
### 横向布局响应式
|
||
|
||
| 屏幕宽度 | 布局行为 |
|
||
|---------|---------|
|
||
| ≥ 1200px | 显示扩展信息区 |
|
||
| < 1200px | 自动隐藏扩展信息区 |
|
||
|
||
```css
|
||
@media (max-width: 1200px) {
|
||
.split-layout-extend-right {
|
||
display: none;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 纵向布局响应式
|
||
|
||
- 扩展区始终占满宽度
|
||
- 高度由内容自适应
|
||
- 通过 `showExtend` 参数控制显示/隐藏
|
||
|
||
## 样式定制
|
||
|
||
组件提供以下 CSS 类名供自定义样式：
|
||
|
||
- `.split-layout` - 布局容器
|
||
- `.split-layout-horizontal` - 横向布局模式
|
||
- `.split-layout-vertical` - 纵向布局模式
|
||
- `.split-layout-main` - 主内容区
|
||
- `.split-layout-extend` - 扩展信息区
|
||
- `.split-layout-extend-right` - 右侧扩展区（横向布局）
|
||
- `.split-layout-extend-top` - 顶部扩展区（纵向布局）
|
||
|
||
### 自定义样式示例
|
||
|
||
```css
|
||
/* 修改扩展区背景色 */
|
||
.split-layout-extend {
|
||
background: #f5f5f5;
|
||
}
|
||
|
||
/* 自定义滚动条样式（横向布局） */
|
||
.split-layout-extend-right::-webkit-scrollbar {
|
||
width: 8px;
|
||
}
|
||
|
||
.split-layout-extend-right::-webkit-scrollbar-thumb {
|
||
background: #1677ff;
|
||
border-radius: 4px;
|
||
}
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
### 1. 横向布局场景
|
||
|
||
- **数据列表 + 信息面板**：左侧显示数据表格，右侧显示统计信息和图表
|
||
- **监控页面**：左侧显示设备列表，右侧显示实时监控数据
|
||
- **内容编辑 + 预览**：左侧编辑器，右侧实时预览
|
||
|
||
### 2. 纵向布局场景
|
||
|
||
- **带统计面板的列表页**：顶部显示统计卡片，下方显示数据列表
|
||
- **可展开的筛选区**：顶部显示筛选条件，下方显示筛选结果
|
||
- **概览信息页**：顶部显示关键指标，下方显示详细数据
|
||
|
||
## 注意事项
|
||
|
||
### 1. 横向布局
|
||
|
||
- **扩展区宽度建议**：320-400px
|
||
- **主内容最小宽度**：确保至少 800px
|
||
- **总宽度建议**：≥ 1200px
|
||
- **扩展区滚动**：自动 sticky 定位，独立滚动
|
||
|
||
### 2. 纵向布局
|
||
|
||
- **扩展区高度**：由内容自适应，不需要设置固定高度
|
||
- **配合 PageTitleBar**：使用 toggle 功能控制显示/隐藏
|
||
- **内容组织**：避免扩展区内容过多，建议不超过 300px 高度
|
||
|
||
### 3. 内容组织
|
||
|
||
- **主内容区**：放置主要内容（列表、表格、表单等）
|
||
- **扩展区**：放置辅助信息（统计、图表、说明等）
|
||
- **避免**：扩展区放置过多交互元素
|
||
|
||
### 4. 性能考虑
|
||
|
||
- 扩展区内容会始终渲染（即使隐藏）
|
||
- 如需完全卸载，使用 `showExtend={false}`
|
||
- 大量图表建议使用懒加载
|
||
|
||
### 5. 布局选择
|
||
|
||
```jsx
|
||
// ✅ 适合横向布局
|
||
- 需要持续展示的监控信息
|
||
- 辅助信息较多且重要
|
||
- 页面宽度充足（> 1200px）
|
||
|
||
// ✅ 适合纵向布局
|
||
- 统计信息可按需展开
|
||
- 移动端友好的布局
|
||
- 扩展内容简洁明了
|
||
|
||
// ❌ 不需要 SplitLayout
|
||
- 简单的列表页面
|
||
- 无扩展信息需求
|
||
- 直接使用 ListActionBar + ListTable
|
||
```
|
||
|
||
## 迁移指南
|
||
|
||
### 从旧版 API 迁移
|
||
|
||
**旧版代码**：
|
||
```jsx
|
||
<SplitLayout
|
||
leftContent={<Content />}
|
||
rightContent={<SideInfoPanel sections={...} />}
|
||
rightWidth={360}
|
||
showRight={true}
|
||
/>
|
||
```
|
||
|
||
**新版代码**：
|
||
```jsx
|
||
<SplitLayout
|
||
direction="horizontal"
|
||
mainContent={<Content />}
|
||
extendContent={<ExtendInfoPanel sections={...} />}
|
||
extendSize={360}
|
||
showExtend={true}
|
||
extendPosition="right"
|
||
/>
|
||
```
|
||
|
||
**变更对照表**：
|
||
|
||
| 旧参数 | 新参数 | 说明 |
|
||
|--------|--------|------|
|
||
| leftContent | mainContent | 主内容区 |
|
||
| rightContent | extendContent | 扩展内容区 |
|
||
| rightWidth | extendSize | 扩展区尺寸 |
|
||
| showRight | showExtend | 显示扩展区 |
|
||
| - | direction | 新增：布局方向 |
|
||
| - | extendPosition | 新增：扩展区位置 |
|
||
|
||
## 配合使用的组件
|
||
|
||
- **ExtendInfoPanel** - 扩展信息面板容器（推荐）
|
||
- **StatCard** - 统计卡片
|
||
- **ChartPanel** - 图表展示
|
||
- **ListTable** - 列表表格
|
||
- **ListActionBar** - 列表操作栏
|
||
- **PageTitleBar** - 页面标题栏（配合纵向布局）
|
||
|
||
## 相关文档
|
||
|
||
- [主内容区布局](../layouts/content-area-layout.md) - 详细的布局使用指南
|
||
- [ExtendInfoPanel](./ExtendInfoPanel.md) - 扩展信息面板组件
|
||
- [StatCard](./StatCard.md) - 统计卡片组件
|
||
- [ChartPanel](./ChartPanel.md) - 图表面板组件
|