96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
## Context
|
||
|
||
恭学教育基地管理后台是一个基于 React 19 + Ant Design v6 的单页应用，服务对象为基地管理人员。当前前端仅有一个 768px 的移动端断点（`MainLayout` 中），且页面级适配不完整：多列表格无横向滚动、仪表盘卡片使用硬编码 `Col span`、弹窗无宽度约束等。管理场景中操作人员可能使用手机、iPad/平板、桌面电脑等不同设备，需要统一的三端响应式体验。
|
||
|
||
**技术约束：**
|
||
- 不引入新的 UI 依赖，保持使用 Ant Design v6
|
||
- 不改动后端 API 和后端逻辑
|
||
- 使用纯 CSS（`@media` queries）+ 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
|
||
|
||
- 无。三端断点、表格策略、拆分字段均已与需求方确认。
|