mula
/
nex_design
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_design/docs/components/SplitLayout.md

12 KiB
Raw Blame History

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                             │
│                                          │
│                                          │
└─────────────────────────────────────────┘

适用场景：

  • 带统计面板的列表页
  • 可展开/收起的筛选条件区
  • 概览信息 + 详细列表

使用示例

基础用法 - 横向布局

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} />
      }
    />
  )
}

纵向布局 + 可折叠

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}
      />
    </>
  )
}

自定义尺寸和间距

<SplitLayout
  direction="horizontal"
  mainContent={<div>主内容</div>}
  extendContent={<div>扩展信息</div>}
  extendSize={400}
  gap={24}
/>

完整示例 - 虚拟机镜像页面

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 结构

横向布局

<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>

纵向布局

<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 自动隐藏扩展信息区 
@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 - 顶部扩展区（纵向布局）

自定义样式示例

/* 修改扩展区背景色 */
.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. 布局选择

// ✅ 适合横向布局
- 需要持续展示的监控信息
- 辅助信息较多且重要
- 页面宽度充足（> 1200px）

// ✅ 适合纵向布局
- 统计信息可按需展开
- 移动端友好的布局
- 扩展内容简洁明了

// ❌ 不需要 SplitLayout
- 简单的列表页面
- 无扩展信息需求
- 直接使用 ListActionBar + ListTable

迁移指南

从旧版 API 迁移

旧版代码：

<SplitLayout
  leftContent={<Content />}
  rightContent={<SideInfoPanel sections={...} />}
  rightWidth={360}
  showRight={true}
/>

新版代码：

<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 - 页面标题栏（配合纵向布局）

相关文档