nex_design_system/docs/04-layout-system.md

5.5 KiB
Raw Blame History

04. Layout System & Page Shells

1. 布局治理原则

NEX 统一的是布局的职责分离、信息层级、响应式和交互质量,不要求所有项目使用相同导航结构或像素尺寸。具体 Shell、导航形态、Header/Sider 尺寸、内容边距、断点和滚动策略由项目规范定义。

2. 页面类型识别

实施前先按用户主要任务识别页面类型,例如:

  • 管理型页面:列表、详情、编辑、设置、权限等。
  • 概览型页面:Dashboard、监控和分析。
  • 专业工作区:文档、聊天、流程、画布、IDE、媒体编辑等。
  • 独立入口:登录、分享、公开展示、向导等。

以上是分类参考,不要求项目必须拥有所有类型。不存在的类型标记 NOT_APPLICABLE。

3. Shell 模式(概念性,不是组件命名要求)

3.1 应用 Shell

适用于需要全局导航、模块切换和统一页面容器的产品。可采用侧边导航、顶部导航、混合导航或其他经过验证的模式。

职责建议:

  • 全局导航、当前上下文和用户入口清晰。
  • 导航区域与主内容区滚动行为明确。
  • 页面内容区域具有可预测的留白和宽度策略。
  • 导航折叠/展开状态可恢复,且键盘操作可达。

3.2 内容/文档工作区

仅在产品存在文档阅读、编辑或文件管理任务时采用。

  • 文件树、工具栏、编辑区/预览区职责分离。
  • 需要独立滚动时,应明确每个滚动容器的边界。
  • 编辑与预览应保持合理一致的内容宽度和阅读节奏。
  • 嵌套 Flex/Grid 子项在需要收缩时检查 min-width: 0、min-height: 0。

3.3 对话工作区

仅在产品存在 AI Chat 或多轮消息任务时采用。

  • 消息历史与输入区职责分离。
  • 输入区在长消息流中保持可达。
  • 会话列表、消息区和工具面板的滚动关系明确。
  • 停止、重试、复制、引用和工具执行状态可理解。

3.4 专业工作台/画布

适用于流程编辑、数据分析、多面板控制和复杂创作任务。

  • 主工作区优先获得足够空间。
  • 可折叠/可调整面板的状态可预测。
  • 拖拽操作应有键盘或其他非拖拽替代路径。
  • 不使用普通后台页面的最大宽度限制挤压画布,除非产品规范明确要求。

3.5 独立页面 Shell

适用于登录、公开分享、邀请和向导等无需完整应用导航的页面。保持品牌和组件语义一致,但不强制显示全局导航。

4. 普通业务页面的信息顺序

可按任务选择:

  1. 页面上下文/标题/面包屑。
  2. 关键指标(只有帮助判断时才展示)。
  3. 搜索、筛选、视图切换或批量操作。
  4. 主内容(表格、卡片、表单、详情或图表)。
  5. 帮助、审计信息或辅助说明。

不要为了填满空间添加没有业务价值的卡片或模块。

5. 响应式布局

  • 优先复用项目已有断点和组件库响应式规则。
  • 不强制采用某一固定断点数值;新增断点必须有真实布局需求和验证依据。
  • 明确桌面、平板、窄屏下导航、表格、表单、工具栏和多栏工作区的变化。
  • 不应简单缩小桌面布局来冒充移动端体验。
  • 避免无意的整页横向滚动;宽表格可按项目设计采用横向滚动或替代呈现。

5.1 命名断点登记与边界测试

项目应优先使用已经存在的断点体系。若标准断点无法满足真实内容布局、信息密度或组件最小宽度要求,可以增加项目级命名断点;不应为了减少断点数量而接受明显的内容遮挡、操作挤压或不合理回退。

每个扩展断点至少登记:

  • 名称和数值/范围(含 min/max 语义);
  • 解决的具体布局问题和涉及组件/页面;
  • 权威定义位置(例如 Tailwind theme、CSS custom properties、媒体查询注册表或设计 Token);
  • 与相邻断点的行为差异;
  • 断点前、断点处、断点后的验证视口;
  • 负责人/批准记录和复审条件。

新增断点必须测试边界两侧,避免只在常见设备预设宽度截图而遗漏临界区间。测试宽度应由实际断点决定,并覆盖项目声明的关键视口。

5.2 导航状态的生命周期

不同导航状态不必合并成一个持久化 Boolean。应按状态语义区分:

  • 用户偏好状态:例如桌面端侧栏折叠/展开,可按产品规范持久化。
  • 临时交互状态:例如移动端 Drawer 当前是否打开,通常只在当前页面会话中有效,不应因刷新而自动保持打开。
  • 共享导航上下文:导航项定义、当前路由、选中状态和权限可共享;这不意味着偏好状态与临时状态必须共用同一状态变量。

状态持久化策略必须符合用户预期,避免移动端刷新后被意外遮罩,也避免桌面端偏好无故丢失。

6. 滚动与尺寸约束

  • 明确页面主滚动容器和嵌套工作区滚动容器。
  • 不要在多个祖先层级重复设置 overflow: auto/hidden 而不清楚滚动归属。
  • 检查长文本、长文件名、代码块、表格和媒体内容是否撑破布局。
  • 固定高度应有产品理由;优先使用父容器约束、弹性布局或视口计算。
  • 对 Flex/Grid 子项检查 min-width: 0 和 min-height: 0,但不要机械地全局添加。

7. 实施前必须记录

页面或 Shell 改造前,记录:

  • 当前 Shell 和导航行为;
  • 关键尺寸的权威来源;
  • 视口变化时的布局行为;
  • 滚动容器归属;
  • 受影响页面清单;
  • 现有视觉截图或可用回归检查。