nex_design/docs/layouts/content-area-layout.md

# 主内容区布局

## 概述

主内容区布局是页面中除了导航栏外的核心内容区域，由 **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`