pay-admin/docs/superpowers/specs/2026-03-30-layout-redesign-design.md

Layout结构优化设计文档

日期: 2026-03-30 项目: 物业缴费管理系统后台 目标: 优化现有layout布局，改为左右结构，白色主题风格

1. 项目背景

当前系统使用UmiJS + Ant Design Pro Layout，采用mix混合布局模式。需要优化为更现代、清晰的左右分栏布局，以白色为主色调，提升用户体验。

2. 需求概述

2.1 布局结构要求

• 左侧区域（垂直分割）：

  • 上方：Logo区域（Logo + 项目名称）
  • 下方：导航菜单

• 右侧区域（垂直分割）：

  • 上方：Header（用户信息、操作按钮）
  • 下方：页面内容区域

2.2 功能要求

• 侧边栏固定宽度220px，支持折叠收起（折叠至64px）
• Logo区域智能显示：展开时显示Logo+文字，折叠时仅显示Logo
• 白色为主色调，整体风格干净整洁
• 保持现有菜单权限系统不变
• 响应式设计支持

3. 设计方案

3.1 整体架构

┌─────────────────────────────────────────────────────┐
│  Layout (side mode)                                  │
│  ┌──────────┬─────────────────────────────────────┐ │
│  │          │  Header (64px, white background)     │ │
│  │   Left   │  ┌───────────────────────────────┐  │ │
│  │  Sidebar │  │ 用户信息区 + 操作按钮          │  │ │
│  │          │  └───────────────────────────────┘  │ │
│  │  ┌──────┐│  ┌───────────────────────────────┐  │ │
│  │  │ Logo ││  │                               │  │ │
│  │  │+Text ││  │   页面内容区域                 │  │ │
│  │  │64px  ││  │   (children渲染)              │  │ │
│  │  ├──────┤│  │   padding: 24px               │  │ │
│  │  │ Menu ││  │                               │  │ │
│  │  │      ││  │                               │  │ │
│  │  └──────┘│  └───────────────────────────────┘  │ │
│  └──────────┴─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

3.2 侧边栏设计（左侧）

Logo区域

• 高度: 64px
• 背景色: #ffffff
• 边框: 底部 1px solid #f0f0f0
• 展开状态: Logo图标(32px) + 项目名称文字
• 折叠状态: 仅显示Logo图标，居中显示
• 动画: 平滑过渡 200ms

菜单区域

• 背景色: #ffffff
• 菜单项高度: 40px
• 菜单文字颜色:
  • 默认: #595959
  • 悬停: #1890ff
  • 激活: #1890ff (背景 #e6f7ff)
• 图标颜色: 跟随文字颜色
• 层级缩进: 每级 20px
• 激活指示器: 左侧蓝色竖线 3px宽

配置参数

siderWidth: 220,
collapsedWidth: 64,
breakpoint: 'lg',
collapsible: true

3.3 Header设计（右侧上方）

布局规格

• 高度: 64px
• 背景色: #ffffff
• 边框: 底部 1px solid #f0f0f0
• 内边距: 0 24px
• 布局: flex左右分布

内容区域

左侧区域（可选）:

• 面包屑导航或页面标题

右侧区域:

• 用户头像（32px圆形）
• 用户名（悬停显示下拉菜单）
• 下拉菜单项：
  • 个人资料
  • 修改密码
  • 退出登录

3.4 内容区域设计（右侧下方）

容器规格

• 背景色: #f5f5f5
• 内边距: 24px
• 最小高度: calc(100vh - 64px)

页面内容（可选包裹）

如果需要卡片包裹：

• 背景色: #ffffff
• 圆角: 8px
• 阴影: 0 1px 2px 0 rgba(0, 0, 0, 0.03)
• 内边距: 24px

3.5 颜色主题规范

主色调

• 主色: #1890ff
• 成功: #52c41a
• 警告: #faad14
• 错误: #ff4d4f
• 信息: #1890ff

中性色

• 标题文字: #262626
• 正文文字: #595959
• 次要文字: #8c8c8c
• 禁用文字: #bfbfbf
• 边框: #d9d9d9
• 分割线: #f0f0f0

背景色

• 布局背景: #f5f5f5
• 侧边栏: #ffffff
• Header: #ffffff
• 内容卡片: #ffffff

3.6 字体规范

• 字号: 14px（基准）
• 行高: 1.5715
• 字体族: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial

3.7 交互和动画

侧边栏折叠

• 动画时长: 200ms
• 动画曲线: cubic-bezier(0.645, 0.045, 0.355, 1.000)
• 折叠时:
  • Logo文字淡出
  • 菜单文字隐藏，图标居中
  • Tooltip显示完整菜单项文字
• 展开时:
  • Logo文字淡入
  • 菜单文字从左侧滑入

菜单交互

• 悬停效果：背景色变化 0.2s
• 子菜单展开：平滑动画
• 激活状态：左侧蓝色竖线指示器

Header交互

• 下拉菜单：淡入动画
• 按钮悬停：背景色变化

4. 技术实现

4.1 核心配置修改

修改 src/common/libs/umi/layoutConfig.tsx:

export const LayoutConfig: RuntimeConfig['layout'] = () => {
  return {
    // 从 'mix' 改为 'side'
    layout: 'side',

    title: '物业管理系统',
    logo: false, // 禁用默认logo，使用自定义

    // 侧边栏配置
    siderWidth: 220,
    collapsedWidth: 64,
    breakpoint: 'lg',

    // 主题token配置
    token: {
      bgLayout: '#f5f5f5',
      header: {
        colorBgHeader: '#ffffff',
        colorHeaderTitle: '#262626',
        colorTextRightActionsItem: '#595959',
        heightLayoutHeader: 64,
      },
      sider: {
        colorMenuBackground: '#ffffff',
        colorMenuText: '#595959',
        colorMenuTextSelected: '#1890ff',
        colorMenuItemBgSelected: '#e6f7ff',
        colorMenuDivider: '#f0f0f0',
      },
    },

    // 自定义Header渲染
    headerRender: (props) => {
      return <CustomHeader {...props} />;
    },

    // 自定义Logo渲染
    logoRenderer: (collapsed) => {
      return <CustomLogo collapsed={collapsed} />;
    },

    // 菜单配置保持不变
    menu: {
      params: snap.session.permissions,
      request: async () => {
        // 现有菜单权限逻辑
      },
    },

    // 其他配置保持不变
    avatarProps: {
      render: () => <AvatarProps user={snap.session.user} />,
    },
  };
};

4.2 新增组件

CustomHeader.tsx

import { Layout, Dropdown, Avatar } from 'antd';
import type { MenuProps } from 'antd';

const { Header } = Layout;

export const CustomHeader = (props: any) => {
  const menuItems: MenuProps['items'] = [
    { key: 'profile', label: '个人资料' },
    { key: 'password', label: '修改密码' },
    { type: 'divider' },
    { key: 'logout', label: '退出登录' },
  ];

  return (
    <Header className="custom-header">
      {/* 左侧：面包屑或页面标题 */}
      <div className="header-left">
        {/* 可选：面包屑导航 */}
      </div>

      {/* 右侧：用户信息 */}
      <div className="header-right">
        <Dropdown menu={{ items: menuItems }} placement="bottomRight">
          <AvatarProps user={user} />
        </Dropdown>
      </div>
    </Header>
  );
};

CustomLogo.tsx

import { MyIcons } from '@/common';

export const CustomLogo = ({ collapsed }: { collapsed: boolean }) => {
  return (
    <div className="custom-logo">
      <div className="logo-icon">
        {/* Logo图标或图片 */}
        <MyIcons.HomeOutlined />
      </div>
      {!collapsed && (
        <div className="logo-text">
          物业管理系统
        </div>
      )}
    </div>
  );
};

4.3 样式文件

在 src/global.less 或组件内部添加：

.custom-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 0 24px;
  background: #ffffff;
  border-bottom: 1px solid #f0f0f0;

  .header-left {
    flex: 1;
  }

  .header-right {
    display: flex;
    align-items: center;
    gap: 16px;
  }
}

.custom-logo {
  display: flex;
  align-items: center;
  height: 64px;
  padding: 0 16px;
  border-bottom: 1px solid #f0f0f0;
  transition: all 0.2s;

  .logo-icon {
    font-size: 32px;
    min-width: 32px;
  }

  .logo-text {
    margin-left: 12px;
    font-size: 16px;
    font-weight: 600;
    color: #262626;
    white-space: nowrap;
    opacity: 1;
    transition: opacity 0.2s;
  }
}

5. 实施计划

5.1 实施步骤

1. 备份当前 layoutConfig.tsx 文件
2. 修改 layout 模式：'mix' → 'side'
3. 更新 token 配置为白色主题
4. 创建 CustomHeader.tsx 组件
5. 创建 CustomLogo.tsx 组件
6. 在 layoutConfig.tsx 中集成自定义组件
7. 测试侧边栏折叠/展开功能
8. 测试菜单导航和权限控制
9. 测试响应式布局
10. 调整细节样式和动画

5.2 文件修改清单

需要修改:

• src/common/libs/umi/layoutConfig.tsx - 主要配置修改

需要新建:

• src/common/components/layout/CustomHeader.tsx
• src/common/components/layout/CustomLogo.tsx

可能修改:

• src/global.less - 全局样式调整

无需修改:

• 菜单权限逻辑（loopMenu 函数）
• 用户信息组件（AvatarProps）
• 页面路由和业务组件
• src/app.tsx 配置

5.3 兼容性保证

保持不变的功能:

• ✅ 菜单权限系统
• ✅ 用户登录状态
• ✅ 路由跳转逻辑
• ✅ 页面内容渲染
• ✅ 现有业务组件

优化改进的功能:

• 🎨 布局结构和视觉风格
• 🎨 主题色和配色方案
• 🎨 交互体验和动画效果

6. 测试要点

6.1 功能测试

• 侧边栏折叠/展开正常工作
• 菜单项点击导航正确
• 菜单激活状态正确显示
• 用户信息下拉菜单功能正常
• 所有页面路由可正常访问

6.2 样式测试

• 白色主题在所有页面正常显示
• Logo展开/折叠切换流畅
• 菜单悬停和激活状态样式正确
• Header样式和布局正确
• 内容区域内边距和背景正确

6.3 响应式测试

• 桌面端（>1024px）显示正常
• 平板端（768px-1024px）显示正常
• 移动端（<768px）侧边栏自动收起
• 各断点下布局无错位

6.4 兼容性测试

• 表单页面显示正常
• 表格页面显示正常
• 弹窗和抽屉组件正常
• 现有业务功能无异常

7. 风险和注意事项

7.1 潜在风险

• 样式冲突: Ant Design版本升级可能导致样式变化
• 浏览器兼容: CSS动画在旧浏览器可能不支持
• 性能影响: 过多动画可能影响低端设备性能

7.2 缓解措施

• 在主流浏览器中测试（Chrome, Firefox, Safari, Edge）
• 使用CSS @supports检测动画支持
• 优化动画性能，使用 transform 和 opacity
• 提供关闭动画的选项（如果需要）

7.3 回滚方案

• 保留原 layoutConfig.tsx 备份
• 使用git版本控制，可随时回退
• 分阶段发布，先在测试环境验证

8. 后续优化建议

8.1 短期优化

• 添加暗色模式切换（可选）
• 优化移动端触摸体验
• 添加快捷键支持

8.2 长期优化

• 考虑使用ProLayout替代UmiJS Layout（如需要更多功能）
• 添加主题定制功能
• 实现布局配置持久化（记住用户的折叠状态等）

9. 验收标准

项目完成需满足以下标准：

1. ✅ 布局结构符合设计要求（左右分栏）
2. ✅ 侧边栏可正常折叠和展开
3. ✅ 白色主题在所有页面正确显示
4. ✅ 菜单权限系统正常工作
5. ✅ 所有页面路由和功能无异常
6. ✅ 响应式布局在不同设备正常
7. ✅ 交互动画流畅自然
8. ✅ 通过所有测试要点

10. 附录

10.1 参考文档

• UmiJS Layout配置
• Ant Design Layout组件
• Ant Design 主题定制

10.2 设计原则

• 简洁: 去除不必要的装饰和元素
• 一致: 保持整体风格统一
• 高效: 快速加载和响应
• 易用: 直观的交互和导航