169 lines
4.5 KiB
Markdown
169 lines
4.5 KiB
Markdown
# Frontend Layout Guidelines
|
|
|
|
本项目后台页面默认遵循“单屏工作区”布局规范。目标不是让页面永远不溢出，而是确保在常见桌面视口下：
|
|
|
|
- 页面主结构能在一屏内看清
|
|
- 用户能同时看到页头、摘要区和主工作区
|
|
- 超出的内容在模块内部滚动，而不是把整页纵向撑爆
|
|
|
|
当前推荐参考实现：
|
|
|
|
- [frontend/src/pages/BGP/BGP.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/BGP/BGP.tsx)
|
|
- [frontend/src/index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)
|
|
|
|
## 核心原则
|
|
|
|
### 1. 页面优先保证一屏工作区
|
|
|
|
管理页默认采用：
|
|
|
|
- 页头：标题、说明、主要操作
|
|
- 主工作区：统计卡、表格、图表、列表、标签页
|
|
|
|
推荐结构：
|
|
|
|
```tsx
|
|
<AppLayout>
|
|
<div className="page-shell">
|
|
<div className="page-shell__header">...</div>
|
|
<div className="page-shell__body">...</div>
|
|
</div>
|
|
</AppLayout>
|
|
```
|
|
|
|
页面总高度应被限制在 `AppLayout` 内容区内，而不是继续让整个页面自然向下增长。
|
|
|
|
### 2. 滚动优先发生在模块内部
|
|
|
|
如果表格、日志、长列表、图表明细超出空间：
|
|
|
|
- 让卡片内部滚动
|
|
- 让表格内部滚动
|
|
- 让标签页内容区内部滚动
|
|
|
|
不要默认依赖整个页面滚动去“解决”空间问题。
|
|
|
|
### 3. 主工作区必须拿到主要空间
|
|
|
|
页面里最重要的模块必须是视觉和空间上的主角。通常应保证：
|
|
|
|
- 页头始终可见
|
|
- 摘要区高度被控制
|
|
- 主表格 / 主图表 / 主分析区占据 50% 以上可视高度
|
|
|
|
如果一个页面有多个大模块，优先顺序是：
|
|
|
|
1. 先压缩说明区和摘要区
|
|
2. 再把次级模块收进标签页或切换视图
|
|
3. 最后才考虑继续增加整页滚动
|
|
|
|
### 4. 小屏幕和高缩放必须进入紧凑模式
|
|
|
|
在窗口高度较低、宽度较窄、或系统缩放较高时，应主动切换紧凑布局，例如：
|
|
|
|
- 缩小卡片 padding
|
|
- 缩小表头和单元格间距
|
|
- 将摘要区改为更紧凑的单行/横向滚动布局
|
|
- 将次级模块移入标签页、抽屉、折叠区
|
|
|
|
紧凑模式的目标是保持可用，不是单纯把文字和控件一股脑缩小。
|
|
|
|
### 5. overflow 责任必须明确
|
|
|
|
页面中的大块内容必须明确：
|
|
|
|
- 谁负责占满剩余高度
|
|
- 谁负责裁剪
|
|
- 谁负责滚动
|
|
|
|
常见要求：
|
|
|
|
- 父容器链路需要 `min-height: 0`
|
|
- 工作区容器通常需要 `display: flex`
|
|
- 真正的滚动节点要显式 `overflow: auto`
|
|
|
|
## 推荐实现模式
|
|
|
|
### 页面骨架
|
|
|
|
优先复用项目里已有的通用结构：
|
|
|
|
- `.dashboard-content-inner`
|
|
- `.page-shell`
|
|
- `.page-shell__header`
|
|
- `.page-shell__body`
|
|
- `.table-scroll-region`
|
|
|
|
不要每个页面都重新发明一套完全不同的高度和滚动语义。
|
|
|
|
### 表格工作区
|
|
|
|
推荐模式：
|
|
|
|
```tsx
|
|
<Card>
|
|
<div className="table-scroll-region" ref={tableRegionRef}>
|
|
<Table
|
|
pagination={false}
|
|
scroll={{ x: 1200, y: tableHeight }}
|
|
/>
|
|
</div>
|
|
</Card>
|
|
```
|
|
|
|
要求：
|
|
|
|
- 表格尽量在卡片内部滚动
|
|
- `scroll.y` 应来自实际可用高度估算，而不是完全静态的魔法数字
|
|
- 父容器链路要保证 header、body、content 的 overflow 都在表格内部闭合
|
|
|
|
### 多模块页面
|
|
|
|
如果一个页面同时有：
|
|
|
|
- 摘要卡
|
|
- 表格
|
|
- 异常明细
|
|
- 最近事件
|
|
|
|
不建议简单纵向堆叠全部模块。优先使用：
|
|
|
|
- 顶部摘要 + 底部单一主工作区
|
|
- 标签页切换多个次级数据视图
|
|
- 左右分栏，并保证每栏内部独立滚动
|
|
|
|
## 不推荐的做法
|
|
|
|
以下模式默认视为不符合本项目页面规范：
|
|
|
|
- 依赖整页纵向滚动来显示主要工作区
|
|
- 一个页面纵向堆 3 到 4 个大卡片，每个都想完整展示
|
|
- 表格没有内部滚动，导致缩放后只能看到 1 到 2 行数据
|
|
- 父容器缺少 `min-height: 0`，导致内部滚动失效
|
|
- 只做视觉缩小，不处理真正的空间分配
|
|
|
|
## 页面验收检查清单
|
|
|
|
提交前至少检查：
|
|
|
|
- 页头、摘要区、主工作区能否同时出现
|
|
- 主工作区是否拿到了页面中最多的高度
|
|
- 表格或明细溢出时，滚动条是否出现在模块内部
|
|
- 浏览器缩放到 `125%` / `150%` 时是否仍可用
|
|
- 低高度窗口下是否还保有合理的可见内容行数
|
|
- Tabs、Card、Table 在 overflow 时是否仍可操作
|
|
|
|
## 落地顺序
|
|
|
|
后续新增或重构后台页时，优先按这个顺序设计：
|
|
|
|
1. 先定义主工作区
|
|
2. 再确定哪些模块必须常驻可见
|
|
3. 最后再做样式和视觉层次
|
|
|
|
简单说：
|
|
|
|
- 先保证空间分配正确
|
|
- 再处理滚动边界
|
|
- 最后再做美化
|