主-详情布局系统

主-详情布局系统 是做什么的？

目的

主-详情布局系统（亦称为分屏或列表-详情UI）为标准化的视觉布局与交互框架，用于浏览主要项目列表（“主”窗格），同时在相邻同步的工作区（“详情”窗格）中显示当前选中记录的完整属性、上下文操作和深层历史。

主-详情模式是高效率网页生产力应用的基础，例如邮件客户端、客户支持服务台、CRM商机查看器、代码审查平台、审计日志以及云资源控制台。

设计有效的主-详情界面需要精确的空间比例、独立的垂直高度约束（避免页面全局滚动）、清晰的视觉选中状态、无缝的多窗格同步，以及在移动视口中从并排分屏视图到单窗格返回堆栈导航的流畅过渡，同时严格遵循WCAG 2.1 AA无障碍指南中关于焦点管理和键盘导航的要求。

用例

• 服务台与客户支持门户： 在主窗格中浏览工单列表，同时在详情窗格中阅读完整的对话线程、客户历史记录和内部备注。
• 企业CRM与销售管道： 在主窗格中扫描联系人或账户，同时在详情窗格中查看商机阶段历史、即将进行的活动和联系人详情。
• 网页邮件与消息应用： 在左侧主列中查看收件箱，同时在右侧详情窗格中阅读、回复或归档当前消息。
• DevOps与云检视仪表盘： 在主窗格中筛选服务器实例、日志流或部署管道，同时在详情窗格中查看实时指标、错误追踪和YAML配置。
• HR与申请人追踪系统（ATS）： 并排浏览候选人申请，同时查看简历、面试评分和安排工具。

何时避免使用

• 需要多行比较的表格数据工作区： 如果用户需要同时跨多个结构属性比较数十条记录，请使用 data-table-ui-system。
• 工作流管道看板： 对于卡片在离散管道阶段之间水平移动的状态列工作流，请使用 kanban-board-ui-system。
• 层级文档树： 对于深层嵌套的树状文档导航（如文件系统目录树），请使用 tree-view-navigation-system。
• 线性分步向导： 对于每个视图建立在前一个视图基础上的顺序多步表单，请使用 step-progress-system 或 multi-step-form-implementation。
• 简单独立着陆页： 对于内容垂直流动在单列的营销着陆页或简单线性文章流，请使用 article-layout-system 或 section-composition-system。

输入

1. 信息架构与项目模式： 主项目卡片（如状态徽章、主题、主要元数据、时间戳）与详情工作区（完整记录正文、活动历史、相关记录、上下文操作栏）中要呈现的属性。
2. 视口外壳上下文： 由外部应用外壳（dashboard-layout-system 或 sidebar-navigation-system）提供的布局边界。
3. 窗格宽度比例偏好： 列尺寸要求（如固定主窗格宽度 360px + 自适应详情窗格 flex: 1，或百分比分割 35% / 65%）。
4. 设计令牌： 表面高度、中性边框、焦点环指示器和字体比例（accessible-color-system、elevation-and-depth-system、fluid-spacing-system）。

输出

1. 分屏布局规范： 用于固定与自适应窗格比例、独立垂直滚动容器（overflow-y: auto）和视觉分隔线的CSS Grid / Flexbox空间定义。
2. 主项目选中与激活状态蓝图： 列表中未读、悬停、聚焦、选中（aria-selected="true"）和多选复选框状态的视觉规范。
3. 详情工作区层级与页眉结构： 详情视图操作栏（粘性页眉、返回按钮、状态控件、主要/次要操作触发器）和内容标签页/区段的空间布局。
4. 响应式视口适配模型： 从桌面端/笔记本电脑的双窗格分屏视图切换到平板/移动端带面板滑动动画的单窗格返回堆栈导航的逐步布局过渡规则。
5. 可访问键盘与ARIA交互模型： 焦点陷阱、移动 tabindex 或APG Listbox焦点路由、ARIA地标（role="region"、aria-controls），以及通过 aria-live="polite" 进行的屏幕阅读器状态通知。

---

工作流

1. 建立双窗格画布容器

在应用外壳（dashboard-layout-system）内构建外部主-详情包装器：

• 容器视口锁定： 将外部包装器设置为 display: flex; height: 100vh; max-height: 100vh; overflow: hidden;（或适配父仪表盘内容区域），以锁定整体布局高度并消除浏览器级别窗口滚动。
• 分割比例列网格： 使用CSS Grid或Flexbox定义分屏比例：
  • 固定主窗格模式（推荐用于收件箱/CRM）： grid-template-columns: minmax(300px, 380px) 1fr;（主窗格保持在300px至380px的舒适扫描宽度；详情窗格消耗所有剩余水平空间）。
  • 比例分割模式： grid-template-columns: 35% 65%; 或 40% 60% 适用于密集检视工具。
• 视觉窗格分隔线： 在窗格之间插入1px实线边框（border-right: 1px solid var(--border-subtle)）或可访问的可调整大小分割条（accessible-split-pane-implementation）。

2. 设计主列表窗格结构

主窗格作为记录集合的快速扫描索引：

• 粘性页眉区域： 在主窗格顶部放置一个固定的搜索和筛选控件栏（flex-shrink: 0; padding: 12px 16px; border-bottom: 1px solid var(--border-subtle); background: var(--surface-card)）。包括快速搜索字段（search-interface-system）、筛选标签和批量操作触发器。
• 独立可滚动项目列表： 将列表项包装在容器中，使用 flex: 1; overflow-y: auto; overflow-x: hidden; -webkit-overflow-scrolling: touch;（role="list" 或 role="listbox"）。
• 主项目卡片结构：
  1. 顶行： 主标识符/作者（font-weight: 600; font-size: 0.875rem; color: var(--text-primary)）、状态药片/徽章和时间戳（font-size: 0.75rem; color: var(--text-muted)）。
  2. 中间行： 项目主题或标题（font-weight: 500; font-size: 0.875rem; color: var(--text-primary); text-truncate: 1 line）。
  3. 底行： 片段或预览文本（font-size: 0.8125rem; color: var(--text-secondary); line-clamp: 2）、标签/类别和分配人头像（user-avatar-system）。
• 状态样式规则：
  • 未读/未处理状态： 粗体标题文字，附带微妙的视觉提示（例如，左侧8x8px主要强调色圆点）。
  • 悬停状态： 背景高亮（background: var(--surface-hover); cursor: pointer）。
  • 激活/选中状态： 明显的激活表面背景（background: var(--surface-active-subtle)）、左侧边框上3px实线主要强调色指示条（border-left: 3px solid var(--brand-primary)）以及 aria-selected="true"。
  • 焦点可见状态： 高度可见的焦点轮廓（outline: 2px solid var(--focus-ring); outline-offset: -2px）。

3. 构建详情工作区窗格结构

详情窗格呈现激活记录的完整上下文和工作区：

• 空状态显示： 当主窗格中未选中任何记录时，在详情窗格中显示一个可访问的空状态（empty-state-system），带有微妙的图标、清晰的标题（“未选中记录”）和有用的提示（“从列表中选择一个项目以查看详情”）。
• 粘性详情操作栏： 在详情窗格内渲染一个持久的顶部页眉栏（position: sticky; top: 0; z-index: 10; display: flex; align-items: center; justify-content: space-between; padding: 12px 24px; border-bottom: 1px solid var(--border-subtle); background: var(--surface-card)）：
  • 移动端返回触发器： 包含一个在桌面端隐藏的“返回列表”按钮（<button class="mobile-back-btn">← 返回</button>）。
  • 记录标识： 记录ID/标题摘要（font-weight: 600; font-size: 1rem）。
  • 操作控件： 主要操作按钮（例如“回复”、“编辑”、“分配”、“删除”），使用 button-and-action-system 样式。
• 独立内容滚动区域： 将主要内容正文包装在滚动容器中（flex: 1; overflow-y: auto; padding: 24px）。
• 详情内容布局：
  • 页眉部分： H1记录标题、状态徽章、元数据网格（创建日期、作者、优先级、分配人）。
  • 主正文区域： 完整描述、HTML线程消息或配置文件代码块。
  • 标签式子区段： 使用标签（tab-ui-system）分隔“活动历史”、“附件”、“审计日志”和“相关记录”。

4. 实现移动端与平板响应式返回堆栈导航

在窄于 768px（对于密集型应用或 1024px）的屏幕上，并排显示窗格会导致文本不可读且按钮拥挤。应将布局转换为单窗格返回堆栈模型：

• 移动端单窗格视图： 一次仅渲染一个窗格，宽度为全视口（width: 100%）。
• 导航状态机：
  • 状态A（主窗格激活）： 主列表窗格占用100%宽度。详情窗格在视觉上隐藏（display: none 或通过 transform: translateX(100%) 平移出屏幕）。
  • 状态B（详情窗格激活）： 当用户点击主项目时，切换视口。详情窗格占用100%宽度，主窗格隐藏。
• 移动端返回按钮： 在状态B中，详情窗格显示一个突出的左上角“返回列表”按钮。点击它将状态机重置回状态A，并将键盘焦点返回到之前选中的主列表项。
• 视口动画： 使用平滑的滑动视图过渡（view-transitions-implementation 或水平CSS变换 transform 0.25s ease-in-out）以增强方向感（向左滑动进入详情，向右滑动返回主列表）。

5. 确保可访问的焦点与屏幕阅读器交互

• ARIA地标与区域角色： 为主窗格容器分配 role="region" aria-label="项目列表"，为详情窗格容器分配 role="region" aria-label="项目详情工作区"。
• 列表框/选择标记： 如果主列表表现为单选组件，则对列表应用 role="listbox" aria-label="..."，对列表项应用 role="option" aria-selected="true|false"。或者，使用标准 <nav> 配合 aria-current="page" 或 aria-current="true"。
• 记录选择时的焦点管理： 当用户使用键盘或指针选择主项目时：
  • 如果用户正在使用箭头键（上 / 下）快速扫描，则将键盘焦点保留在主列表内。
  • 异步更新详情窗格DOM，并通过 aria-live="polite" 状态区域宣布记录加载：“已加载工单 #1042：支付处理错误”。
  • 当用户从选中的列表项按下 Enter 或 Tab 时，无缝地将焦点移动到详情窗格的主要操作或页眉H1（tabindex="-1"）。
• 移动端视口焦点陷阱与恢复： 在移动端切换到详情视图时，自动将焦点移动到移动端返回按钮或详情页眉。返回主视图时，将焦点恢复到之前激活的主项目。

---

决策规则

窗格布局与分割策略

视口宽度	推荐布局模式	主窗格宽度	详情窗格宽度
宽桌面 (>1280px)	双窗格分屏视图（或带侧边的三窗格）	固定 360px - 400px	自适应 flex: 1 (min-width: 600px)
标准桌面 (1024px - 1279px)	双窗格分屏视图	固定 320px - 350px	自适应 flex: 1 (min-width: 480px)
平板 (768px - 1023px)	窄双窗格或单窗格堆栈	固定 280px - 300px（或可折叠）	自适应 flex: 1
移动端 (<768px)	单窗格返回堆栈视图	100%（状态A）	100%（状态B）

主列表选择与焦点模型

• 自动选择聚焦项（快速扫描）： 按下 上 或 下 箭头键立即更改激活选择并实时更新详情窗格。推荐用于电子邮件阅读、日志审计和大量工单筛选。
• 显式选择执行操作（按回车/点击）： 使用箭头键在主项目间导航会移动视觉焦点环，但不更新详情窗格。详情窗格仅在用户显式按下 Enter、Space 或点击时更新。当加载详情记录涉及繁重网络API请求或表单状态编辑时推荐使用。

---

约束

• 无障碍（WCAG 2.1 AA）：
  • SC 2.1.1 键盘： 用户必须能够使用键盘控件独立滚动主项目、选择记录、导航进入详情工作区、触发操作并返回主列表。
  • SC 2.4.7 焦点可见： 激活和聚焦的主项目必须具有未被裁剪的焦点环，且与背景的对比度至少达到3:1。
  • SC 4.1.2 名称、角色、值： 主项目必须通过 aria-selected="true" 或 aria-current="true" 向辅助技术明确传达其激活/选中状态。
  • SC 2.5.8 目标大小： 主列表项和详情操作按钮上的点击目标必须提供至少 24x24px 的目标区域（移动端触摸屏建议44x44px）。
• 布局包含与CLS： 主-详情布局必须锁定整体容器高度（height: 100vh; overflow: hidden）以防止不必要的布局偏移（CLS）。任何内容加载（如骨架屏）不应在应用外壳内的可见滚动区域之外导致页面跳动。
• 性能： 当主列表包含大量数据集（>1000条记录）时，实现虚拟滚动（virtual-scrolling-system）以将DOM节点数保持在300个元素以下。在按需（lazy-load）加载详情记录时，显示骨架屏占位符（skeleton-loading-system）以最小化感知延迟至300毫秒以下。