4.5 KiB
4.5 KiB
Frontend Layout Guidelines
本项目后台页面默认遵循“单屏工作区”布局规范。目标不是让页面永远不溢出，而是确保在常见桌面视口下：
- 页面主结构能在一屏内看清
- 用户能同时看到页头、摘要区和主工作区
- 超出的内容在模块内部滚动，而不是把整页纵向撑爆
当前推荐参考实现：
核心原则
1. 页面优先保证一屏工作区
管理页默认采用：
- 页头：标题、说明、主要操作
- 主工作区：统计卡、表格、图表、列表、标签页
推荐结构：
<AppLayout>
<div className="page-shell">
<div className="page-shell__header">...</div>
<div className="page-shell__body">...</div>
</div>
</AppLayout>
页面总高度应被限制在 AppLayout 内容区内，而不是继续让整个页面自然向下增长。
2. 滚动优先发生在模块内部
如果表格、日志、长列表、图表明细超出空间：
- 让卡片内部滚动
- 让表格内部滚动
- 让标签页内容区内部滚动
不要默认依赖整个页面滚动去“解决”空间问题。
3. 主工作区必须拿到主要空间
页面里最重要的模块必须是视觉和空间上的主角。通常应保证：
- 页头始终可见
- 摘要区高度被控制
- 主表格 / 主图表 / 主分析区占据 50% 以上可视高度
如果一个页面有多个大模块，优先顺序是：
- 先压缩说明区和摘要区
- 再把次级模块收进标签页或切换视图
- 最后才考虑继续增加整页滚动
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
不要每个页面都重新发明一套完全不同的高度和滚动语义。
表格工作区
推荐模式：
<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 时是否仍可操作
落地顺序
后续新增或重构后台页时，优先按这个顺序设计：
- 先定义主工作区
- 再确定哪些模块必须常驻可见
- 最后再做样式和视觉层次
简单说：
- 先保证空间分配正确
- 再处理滚动边界
- 最后再做美化