# 页面布局与间距控制规范

**版本**: v3.8
**更新时间**: 2026-03-24

---

## 📋 一、路由与页面布局对应表

### 1.1 主布局容器

所有页面都使用统一的布局结构：

```
<div className="page-container">          ← 页面容器（全局统一）
    <div className="list-header">         ← 标题区域
        <h1>页面标题</h1>
        <p>页面描述</p>
        <div className="list-header-actions">
            <Button>创建</Button>
        </div>
    </div>
    
    <GuideTips />                         ← Tips 提示（可选）
    
    <FilterBar />                         ← 筛选工具栏（可选）
    
    <div className="content-section">     ← 内容区块（白色背景）
        {/* 表格/卡片/列表等 */}
    </div>
</div>
```

### 1.2 路由与页面布局详细对应

| 路由 | 页面组件 | 标题 | 筛选栏 | 内容类型 | 使用组件 |
|------|---------|------|--------|---------|---------|
| **`/overview`** | `home/index` | 概览 | ❌ | 统计卡片 | `StatsGrid` |
| **`/appCenter`** | `appPlazaList/index` | 全部 RAG 应用 | ✅ | 卡片网格 | `AppCard` + `.app-card-grid` |
| **`/appCenter/category/*`** | `categoryApps/index` | 分类应用 | ✅ | 卡片网格 | `AppCard` + `.app-card-grid` |
| **`/appCenter/questionAnswer`** | `questionAnswer/list` | 我创建的应用 | ❌ | 卡片网格 | `AppCard` + `.app-card-grid` |
| **`/appCenter/questionAnswer/create`** | `questionAnswer/form` | 创建应用 | ❌ | 表单 | `Step1Drawer` |
| **`/knowledge/knowledgeLib`** | `knowledgeLib/list` | 知识库 | ✅ | 表格 | `Table` |
| **`/knowledge/knowledgeLib/create`** | `knowledgeLib/list` | 创建知识库 | ❌ | 表单 | `InfoModal` |
| **`/system/apiKey`** | `apiKey/index` | API Key 管理 | ✅ | 表格 | `Table` |
| **`/system/audit`** | `audit/index` | 应用审核 | ✅ | 表格 | `Table` |
| **`/universalChat`** | `universalChat/index` | 智能问答 | ❌ | 对话界面 | `ChatInterface` |
| **`/mobile-test`** | `mobile/MobileH5` | H5 测试 | ✅ | 混合 | `FilterBar` + `ChatInterface` |

---

## 📐 二、全局间距控制

### 2.1 间距变量系统

所有间距使用全局变量，定义在 `src/styles/variables.less`：

```less
// 4px 基准间距系统
@spacing-1: 4px;    // 最小间距
@spacing-2: 8px;    // 小间距
@spacing-3: 12px;   // 中等间距
@spacing-4: 16px;   // 标准间距
@spacing-5: 20px;   // 大间距
@spacing-6: 24px;   // 加大间距
@spacing-8: 32px;   // 特大间距
@spacing-10: 40px;  // 页面级间距
```

### 2.2 容器间距控制

#### **页面容器（`.page-container`）**

```less
.page-container {
    padding: @spacing-4 @spacing-6;  // 上下 16px，左右 24px
    min-height: calc(100vh - @header-height);
    background: @bg-primary;
}
```

**修改方式**：
```less
// 在 global.less 中统一修改
.page-container {
    padding: @spacing-6 @spacing-8;  // 改为更宽松的间距
}
```

#### **内容区块（`.content-section`）**

```less
.content-section {
    margin-bottom: @spacing-6;  // 与下一区块间距 24px
    padding: @spacing-4;        // 内边距 20px
    background: @bg-secondary;
    border-radius: @radius-lg;
}
```

**修改方式**：
```less
// 在 global.less 中统一修改
.content-section {
    margin-bottom: @spacing-5;  // 改为 20px
    padding: @spacing-4;        // 改为 16px
}
```

#### **区块间距（`.section-gap`）**

```less
.section-gap {
    margin-bottom: @spacing-5;  // 20px 统一间距
}
```

### 2.3 列表头部间距

```less
.list-header {
    margin-bottom: @spacing-4;  // 与下方内容间距 16px
    padding-bottom: @spacing-3; // 标题栏底部内边距 12px
    border-bottom: 1px solid @border-base;
    
    // 紧跟 GuideTips 时
    &.with-tips {
        margin-bottom: 0;  // 紧贴 GuideTips
    }
}
```

### 2.4 筛选工具栏间距

```less
.filter-bar {
    padding: @spacing-3 0;  // 上下 12px
    margin-bottom: 0;       // 无外边距（让内容容器控制）
}
```

---

## 🎯 三、全局控制方法

### 3.1 修改全局间距（推荐）

**位置**：`src/styles/global.less`

**示例 1**：增加所有页面容器的内边距
```less
// 修改前
.page-container {
    padding: @spacing-4 @spacing-6;  // 16px / 24px
}

// 修改后
.page-container {
    padding: @spacing-6 @spacing-8;  // 24px / 32px - 更宽松
}
```

**示例 2**：统一内容区块间距
```less
// 修改前
.content-section {
    margin-bottom: @spacing-6;  // 24px
}

// 修改后
.content-section {
    margin-bottom: @spacing-5;  // 20px - 更紧凑
}
```

### 3.2 修改特定页面间距

**位置**：页面自己的 `style.less` 文件

**示例**：知识库列表页面增加额外间距
```less
// src/pages/knowledgeLib/list/style.less

.knowledgeLibList {
    // 覆盖全局间距
    .page-container {
        padding-top: @spacing-8;  // 顶部增加间距
    }
    
    .content-section {
        margin-bottom: @spacing-8;  // 增加底部间距
    }
}
```

### 3.3 使用间距工具类

**在 JSX 中使用**：

```tsx
// 增加顶部间距
<div className="mt-4">内容</div>  {/* margin-top: 16px */}

// 增加底部间距
<div className="mb-6">内容</div>  {/* margin-bottom: 24px */}

// 增加内边距
<div className="p-5">内容</div>   {/* padding: 20px */}
```

**可用的工具类**：

| 类名 | 说明 | 值 |
|------|------|-----|
| `.mt-1` ~ `.mt-6` | 上外边距 | 4px ~ 24px |
| `.mb-1` ~ `.mb-6` | 下外边距 | 4px ~ 24px |
| `.p-1` ~ `.p-6` | 内边距 | 4px ~ 24px |

---

## 📊 四、常见布局场景

### 4.1 标准列表页（知识库、API Key、审核）

```tsx
<div className="page-container">
    {/* 标题区域 */}
    <div className="list-header">
        <div className="list-header-title">
            <h1>知识库管理</h1>
            <p>管理您的所有知识库</p>
        </div>
        <div className="list-header-actions">
            <Button type="primary" icon={<PlusOutlined />}>创建</Button>
        </div>
    </div>
    
    {/* Tips 提示 */}
    <GuideTips visible={true} title="..." steps={...} />
    
    {/* 筛选工具栏 */}
    <FilterBar tabs={...} searchValue={...} />
    
    {/* 内容区块 */}
    <div className="content-section">
        <Table ... />
    </div>
</div>
```

**间距说明**：
- `.list-header` → `.guide-tips-wrapper`: 0px (紧贴)
- `.guide-tips-wrapper` → `.filter-bar`: 0px (紧贴)
- `.filter-bar` → `.content-section`: 0px (紧贴)
- `.content-section` 内部：`padding: 20px`

### 4.2 卡片网格页（应用中心）

```tsx
<div className="page-container">
    <div className="list-header">
        <h1>应用中心</h1>
        <p>浏览所有 RAG 应用</p>
    </div>
    
    <FilterBar tabs={...} />
    
    <div className="app-card-grid">
        <AppCard ... />
        <AppCard ... />
    </div>
    
    <div className="pagination-container">
        <Pagination ... />
    </div>
</div>
```

**间距说明**：
- `.filter-bar` → `.app-card-grid`: 0px (紧贴)
- `.app-card-grid` 内部：`gap: 16px`
- `.app-card-grid` → `.pagination-container`: 24px

### 4.3 统计概览页（首页）

```tsx
<div className="page-container">
    <div className="list-header">
        <h1>概览</h1>
        <p>查看系统使用情况</p>
    </div>
    
    <StatsGrid stats={...} />
</div>
```

**间距说明**：
- `.list-header` → `StatsGrid`: 24px (默认)

---

## 🔧 五、快速修改指南

### 5.1 增加所有页面的上下间距

**修改位置**：`src/styles/global.less`

```less
.page-container {
    padding: @spacing-6 @spacing-8;  // 改为 24px / 32px
}
```

### 5.2 增加内容区块之间的间距

```less
.content-section {
    margin-bottom: @spacing-8;  // 改为 32px
}
```

### 5.3 增加标题与内容的间距

```less
.list-header {
    margin-bottom: @spacing-6;  // 改为 24px
}
```

### 5.4 增加筛选栏与内容的间距

**方法 1**：在 `FilterBar` 组件样式中修改
```less
// src/components/common/FilterBar/index.less
.filter-bar {
    margin-bottom: @spacing-4;  // 改为 16px
}
```

**方法 2**：在内容区块上增加上边距
```less
.content-section {
    margin-top: @spacing-4;  // 增加顶部间距 16px
}
```

---

## 📋 六、最佳实践

### ✅ 推荐做法

1. **使用全局变量**
   ```less
   // ✅ 正确
   .my-class {
       margin-bottom: @spacing-5;
   }
   
   // ❌ 错误
   .my-class {
       margin-bottom: 20px;  // 硬编码
   }
   ```

2. **优先修改全局样式**
   ```less
   // ✅ 在 global.less 中统一修改
   .content-section {
       margin-bottom: @spacing-8;
   }
   ```

3. **使用工具类**
   ```tsx
   // ✅ 使用现有工具类
   <div className="mb-4">内容</div>
   ```

### ❌ 避免的做法

1. **不要在组件中硬编码间距**
   ```tsx
   // ❌ 错误
   <div style={{ marginBottom: '20px' }}>内容</div>
   
   // ✅ 正确
   <div className="mb-5">内容</div>
   ```

2. **不要重复定义全局样式**
   ```less
   // ❌ 错误 - 在组件样式中重复定义
   .my-component .content-section {
       margin-bottom: 24px;
   }
   
   // ✅ 正确 - 使用全局类
   <div className="content-section">内容</div>
   ```

---

## 🎯 七、总结

### 全局间距控制层级

```
1. 页面容器 (.page-container)
   └─ padding: @spacing-4 @spacing-6

2. 标题区域 (.list-header)
   └─ margin-bottom: @spacing-4

3. Tips 提示 (.guide-tips-wrapper)
   └─ margin-bottom: @spacing-4

4. 筛选工具栏 (.filter-bar)
   └─ margin-bottom: 0

5. 内容区块 (.content-section)
   └─ margin-bottom: @spacing-6
   └─ padding: @spacing-5
```

### 修改优先级

1. **全局修改** → `src/styles/global.less`
2. **页面特定** → `src/pages/xxx/style.less`
3. **组件特定** → `src/components/xxx/index.less`

---

**文档维护**: AI Assistant
**最后更新**: 2026-03-24
**版本**: v3.8