4.2 KiB
4.2 KiB
Context
恭学教育基地管理后台是一个基于 React 19 + Ant Design v6 的单页应用，服务对象为基地管理人员。当前前端仅有一个 768px 的移动端断点（MainLayout 中），且页面级适配不完整：多列表格无横向滚动、仪表盘卡片使用硬编码 Col span、弹窗无宽度约束等。管理场景中操作人员可能使用手机、iPad/平板、桌面电脑等不同设备，需要统一的三端响应式体验。
技术约束：
- 不引入新的 UI 依赖，保持使用 Ant Design v6
- 不改动后端 API 和后端逻辑
- 使用纯 CSS（
@mediaqueries）+ antd 响应式 props（Row/Col断点、Table scroll）
Goals / Non-Goals
Goals:
- 建立统一的三断点体系：手机
< 768px、平板768-1024px、桌面> 1024px - 所有页面的
<Table>在小屏下可通过横向滚动查看全部列 - 仪表盘统计卡片在平板和手机端自动调整列数
- 登录页在手机上不溢出
- 弹窗在所有端侧不超出屏幕
- ECharts 图表响应容器宽度变化
- 学生管理页「学号/身份证」拆分为两列
- API/数据获取层不变，仅改 UI 渲染层
Non-Goals:
- 不更换组件库或引入 Tailwind CSS 等新样式框架
- 不做列响应式隐藏（表格列全部保留，靠横向滚动）
- 不改变路由和权限体系
- 不涉及服务端渲染或 SSR
- 不添加视觉主题切换能力
Decisions
1. 断点定义与 CSS 组织
| 断点 | 范围 | 典型设备 |
|---|---|---|
xs (手机) |
< 768px | iPhone、Android 手机 |
sm (平板) |
768px - 1024px | iPad 竖屏、小型平板 |
md+ (桌面) |
> 1024px | 笔记本、台式显示器 |
策略：
- 全局样式放在
index.css，使用@media规则 - antd
Row/Col组件使用内置xs/sm/md/lg断点 props - 避免组件内联 style 中的固定像素值，改为 CSS class 或 antd 响应式 props
为什么不引入 CSS 变量/主题系统？
当前项目规模适中（~16 页面），引入 CSS 变量体系增加复杂度但收益有限。直接用 @media queries + antd 响应式 props 即可覆盖。
2. 表格横向滚动策略
决策： 所有 <Table> 统一添加 scroll={{ x: 'max-content' }} 或基于列宽计算的 x 值，移动端通过手指滑动查看全部列。
列宽优化：
- 操作列固定宽度（
width: 120-200），配合fixed: 'right'可选 - 数据列设置合理的
width避免过窄或过宽 - 使用
ellipsis: true防止长文本撑开列宽
为什么不用 antd 的 responsive 列隐藏？
用户明确要求保留全部列、用横向滚动。管理后台数据密集场景下，隐藏列可能导致信息缺失。
3. 布局与侧栏
桌面（> 1024px）： 保持当前 Sider + 内容区布局，侧栏可折叠，content margin 24px。
平板（768-1024px）： Sider 默认折叠（collapsed: true），减少侧栏占用宽度，content margin 16px。
手机（< 768px）： 当前已有 Drawer 替代 Sider，content margin 12px。
4. 仪表盘与图表
统计卡片：
xs={12} sm={12} md={6} // 手机: 2列, 平板: 2列, 桌面: 4列
图表卡片：
xs={24} sm={12} // 手机: 堆叠, 平板及以上: 并排
ECharts 通过 echarts-for-react 的 style={{ width: '100%' }} 自动跟随容器宽度。
5. 弹窗与表单
- Modal 添加
width在桌面固定（400-600），平板/手机使用百分比或max-width约束 - 全局 CSS:
.ant-modal { max-width: calc(100vw - 32px); } - Form 保持
layout="vertical"，天然适配窄屏
Risks / Trade-offs
| 风险 | 缓解 |
|---|---|
| 表格横向滚动在手机上交互不直观 | 添加 scroll={{ x }} 后 antd 自动显示滚动条；操作列可用 fixed: 'right' 固定 |
| ECharts 甘特图在窄屏可能挤缩 | 设置最小高度，必要时在容器上 overflowX: auto |
| 教室排期表（31 天列）表格极宽 | 已有 overflowX: auto，优化列 minWidth 和 sticky 首列 |
| 修改涉及文件多（~18 个），可能引入 layout 抖动 | 每个页面改动后手动验证；改动粒度小（CSS + props），回滚简单 |
Open Questions
- 无。三端断点、表格策略、拆分字段均已与需求方确认。