跳转至

布局区域契约

目的

页面或有界工作区在产品内容添加之前,应具有可预测的结构性区域。构建者可以使用通用 Section、五插槽 Layout 原语或语境化 Toolbar,而无需每个表面自行发明其内边距、边界、区域方向或内容所有权。AppShell 拥有页面外壳,负责将这些较低层区域与应用导航组合在一起。

成员规则

一个组件若其主要公共用途是定义稳定的结构区域,则属于本契约:通用页面/内容区域、Layout 五插槽拓扑中的具名位置,或语境化操作区域。成员可以组合共享布局原语,但它们拥有的边界比单纯任意子元素排列更强。

  • 成员: Section;Layout 及其 Header、Content、Footer 和 Panel 区域;Toolbar。
  • 协作者: family:layout-primitives 提供任意子元素排列工具;architecture:container-padding 提供更广泛的内边距和出血系统,供 Section、Layout 及其区域、Table、Toolbar 和 Divider 使用;useResizable 和 ResizeHandle 可驱动面板尺寸;AppShell 拥有页面外壳,并将 Layout 与应用导航组合;组件主题化拥有视觉目标。
  • 排除项: Stack、Grid、Center 及其修饰符排列任意子元素,不声称拥有结构区域。FormLayout 拥有字段特定的排列和可选项。Card 是离散项目表面。AppShell 拥有页面外壳和导航语义,而非此可复用区域语法。Table 拥有结构化数据,Divider 拥有分隔;它们参与 architecture:container-padding 并不使二者成为布局区域成员。

一个组件不会仅仅因为恰好渲染了 flex 行、带内边距的包装器或类似标题的视觉处理而加入。

共享所有者

  • Section 拥有通用的带绘制页面/内容区域,包括其变体、选定的分隔线边缘、组件内边距以及嵌套 Section 行为。
  • Layout 拥有其五插槽拓扑、插槽存在性、区域位置、共享外/内内边距、高度模式、内容宽度传播以及默认 header/footer 分隔线上下文。它不拥有页面外壳。
  • LayoutHeader、LayoutContent、LayoutFooter 和 LayoutPanel 拥有各自的区域元素、可选地标角色/名称、局部内边距以及区域特有的尺寸或滚动行为。
  • Toolbar 拥有语境化操作区域、其 start/center/end 车道、工具栏语义、键盘移动和尺寸级联。它将绘制的表面、变体和选定的分隔线边缘委托给 Section。
  • architecture:container-padding 拥有继承的内边距和出血机制。
  • useResizable 和 ResizeHandle 拥有调整大小状态和交互。LayoutPanel 接受它们的当前尺寸作为替代宽度所有者,将其元素借给调整大小控制器以在折叠和展开时显示边缘,并拥有折叠面板的焦点移动和 inert 状态(component:LayoutPanel FR7, AR2)。

规范概念

概念 值或状态 默认语义 稳定性
通用区域 Section 相关的页面/内容区域,可选带绘制处理 当前
五插槽拓扑 header、start、content、end、footer Layout 将提供的区域按逻辑阅读方向放置 当前
语境化操作 start、可选 center、end Toolbar 将控件分组在受限内容区域内 当前
外/内内边距 Layout 边缘或相邻区域边缘 Layout 区域使用与其接触边缘相适应的内边距 当前
边界 无或分隔线 成员只能绘制其组件契约暴露的边缘 当前
区域滚动 裁剪、可滚动,或在暴露处由页面拥有 LayoutContent 和 LayoutPanel 拥有当前的溢出选择 组件所有
地标 无显式角色,或由调用方提供的角色和标签 区域不会根据视觉位置推断页面级地标语义 当前
区域尺寸 固有、固定、fill/auto、封顶,或在暴露处由调整大小驱动 每个成员拥有其适用的尺寸轴 组件所有
响应式适配 保留、省略,或由调用方组合替换 不存在共享的自动区域切换 调用方/组件所有

跨组件不变量

  • FR1 — 区域拥有结构,而非产品含义。 成员建立空间边界并渲染调用方内容,而不采用内容的产品语义、状态或组件契约。Toolbar 对其各个按钮的按下跟踪(family:action-groups FR5)是唯一例外。
  • FR2 — 区域方向是逻辑化的。 start 和 end 遵循书写方向。分隔线放置和面板相邻关系使用相同的逻辑区域位置。
  • FR3 — Layout 根据插槽存在情况选择几何。 Header、Content、Footer 和 Panel 在接触 Layout 边界处应用外内边距,在遇到另一个区域处应用内内边距。LayoutContent 将其根节点保留为滚动、内边距和直接子元素的所有者。被省略的插槽不会留下区域包装器。每个区域会重新发布其应用于全出血后代的几何(architecture:container-padding INV2)。
  • FR4 — 显式区域内边距替代自动应用的内边距。 Section 发布其组件内边距;Layout 将外/内内边距分配到其具名插槽;区域的显式内边距或零内边距路径选择其本地样式。自动 Layout 边缘会重新发布其应用的内边距,但 LayoutContent 的内容宽度沟槽除外(component:LayoutContent FR2)。
  • FR5 — 在组合允许两个所有者的情况下,边界所有权由调用方选择。 LayoutHeader 和 LayoutFooter 各自拥有其隐含边缘。Section 和 Toolbar 暴露选定的边缘。LayoutPanel 可绘制其面向内容的边缘,ResizeHandle 也可绘制该边缘;当前代码不阻止两者同时存在。可调整大小的面板组合在相邻 ResizeHandle 拥有分隔线时,必须将 LayoutPanel hasDivider={false} 设置为 false。
  • FR6 — 分隔线缺失可能改变间距。 Layout 区域目前会折叠与缺失的 header、footer 或 panel 分隔线相关的内部间距;显式分隔线会保留围栏边界。
  • FR7 — 滚动是显式且局部的。 LayoutContent 和 LayoutPanel 拥有当前的 isScrollable 行为。Section 和 Toolbar 不会因为家族成员身份而成为滚动容器。Layout height="fill" 包含区域滚动;height="auto" 让包含的页面增长。
  • FR8 — 地标语义保持显式。 具名的视觉位置不会自动分配 banner、main、navigation、complementary 或 contentinfo。调用方为上下文提供受支持的角色和标签。
  • FR9 — 响应式替换不是自动的。 Section 和 Toolbar 保持当前的呈现方式。Layout 渲染调用方提供的区域。AppShell、产品组合或其他特定组件所有者决定在较窄宽度下何时省略或替换区域。AppShell 在跨越移动断点时保持主内容挂载(状态保留)。
  • FR10 — 调整大小所有权保持委托。 带有 resizable 的 LayoutPanel 使用 hook 提供的当前尺寸,而不是其 width prop。区域家族不会重新定义吸附、持久化、折叠、键盘或指针行为。
  • FR11 — 主题化保持组件所有。 结构成员身份不会创建家族目标。当前的 .doc.mjs 元数据记录已交付的目标和能力,运行时 themeProps() 发出它们,architecture:component-theming-surface 拥有跨组件规则。组件规范可在存在时添加可选的解剖结构映射元数据。
  • FR12 — 内容宽度将滚动条保持在开放的内容边缘。 当设置了 contentWidth 但没有面板时,LayoutContent 跨越可用的中间区域,并通过上下文感知的内联内边距对齐其直接子元素。当恰好有一个面板时,该面板保持与居中框架对齐,而 LayoutContent 延伸到相对的开放侧。镜像的 start/end 情况使用相同规则。当有两个面板时,完整的中间组合保持受限。百分比和固有宽度值以及裸变量保持受限组合,因为它们无法安全共享同一对齐基准;calc(var(...)) 是显式长度值变量路径。

允许的组件变体

  • AV1 — 区域强度。 Section 是一个通用区域;Layout 成员是五槽位原语中感知位置的槽位;Toolbar 是语义化操作栏。
  • AV2 — 表面处理。 Section 和 Toolbar 可以使用 Section 变体及选定的边。Layout 区域使用其现有的分隔线和内边距处理。家族成员身份不会统一其视觉 API。
  • AV3 — 区域内容。 Header、footer、panel、content 和 toolbar 通道可以容纳其组件契约允许的任何内容。
  • AV4 — 尺寸模型。 Layout 拥有填充/自动容器高度和内容宽度传播;各个区域拥有适用的高度、宽度、内边距和滚动属性;Section 拥有其盒尺寸属性。
  • AV5 — 交互。 Toolbar 拥有漫游焦点、键盘提示以及 FR5 赋予其按钮的按下跟踪 family:action-groups。其他成员不添加工具栏行为。Resizable 拥有调整大小交互。
  • AV6 — 组合机制。 成员可以使用 Stack 工具、直接 CSS 布局、上下文或组件组合。可观察的区域契约是所拥有的表面。
  • AV7 — 响应式策略。 调用者可以省略、替换或从外部调整区域。该家族不设置断点。

代表性矩阵

成员及状态 共享不变量 有意的变体
Section / 默认、透明或 muted 拥有一个通用区域并发布其应用的内边距 变体和选定的分隔线边缘是 Section 本地的
Layout / 仅内容 槽位存在性选择 Layout 边缘内边距 使用 contentWidth 时,LayoutContent 跨越中间区域,在内部对齐子项,并将其滚动条保持在 Layout 边缘
Layout / 所有区域 开始/结束保持逻辑性;命名区域接收外部/内部内边距 当只有一个面板时,内容延伸到对面开放边缘;当两个面板都存在时,完整组合保持受限
LayoutHeader 或 LayoutFooter / 分隔线继承 一个边界拥有者和明确的 landmark 语义 父级 defaultHasDividers 提供默认值;本地 false 可以覆盖它
LayoutContent / 可滚动或页面所属 区域拥有当前的溢出选择 isScrollable={false} 支持父级/页面滚动以及粘性后代
LayoutPanel / 固定或由调整大小驱动 面板位置选择边缘处理 useResizable 可以替换宽度所有权;ResizeHandle 保留交互所有权
Toolbar / 两条或三条通道 上下文操作区域将其表面委托给 Section 中心内容切换内部布局;工具栏单独拥有键盘行为

采用与例外

组件或关注点 采用 当前差距或例外
Section 通用区域和容器内边距发布者 其嵌套逃逸始终是内联的,但仅在块轴上是第一个/最后一个子元素
Layout container 拥有五个槽位及槽位上下文的区域所有者 仅内容的 LayoutContent 保持全宽,并通过内边距对齐直接子元素。当只有一个面板时,面板保持对齐,而内容延伸到对面开放边缘。当两个面板都存在或内容宽度为固有宽度时,中间组合保持受限。测试覆盖拓扑;浏览器证据覆盖镜像对齐和滚动条位置。
LayoutContent 读取槽位存在性并应用外部/内部内边距 每个边缘发布其应用的内边距;各边缘的内边距及其发布仅有审计浏览器凭证,而非始终运行的检查
LayoutPanel 应用位置感知的内边距,并可以接受由调整大小驱动的宽度 自动 Layout 边缘内边距会保留基线内部几何变量;相邻的 ResizeHandle hasDivider 可能会导致线条加倍,除非调用者设置面板 hasDivider={false}
LayoutHeader/Footer 区域特定的 inset、边界和地标 跨区域的计算样式一致性未由单一浏览器矩阵覆盖
Toolbar 由 Section 支撑的表面及工具栏行为 内联 inset 和边缘补偿遵循所组合 Section 的当前内边距上下文
响应式区域 调用方/AppShell 组合 LayoutPanel 当前没有共享的响应式可见性契约

这些行描述了已发布的行为和验证差距。它们并非已批准的例外,不应在文档拉取请求中被悄然更改。

变更耦合

  • 添加或更改结构区域组件时,需检查成员资格,并且仅在共享边界发生变化时才更新此契约。
  • 更改 Layout 槽位存在性、区域上下文、inset 分配、分隔线继承、高度模式或内容宽度传播时,更新相应的区域测试和浏览器证据。
  • 更改 Section 内边距、嵌套转义、变体或分隔线行为时,更新其组件契约;当继承的几何属性发生变化时,审查 architecture:container-padding。
  • 更改 Toolbar 车道、语义、键盘行为或尺寸级联仍属于 Toolbar 的工作;更改其由 Section 支撑的表面或 inset 关系时,还需审查本家族及 container-padding 架构。
  • 更改 LayoutPanel 的调整大小集成时,审查 Resizable 的组件契约,但不应将调整大小机制复制到本家族中。
  • 添加响应式隐藏/切换行为需要组件或更高级别的所有者以及兼容性证据;家族成员身份并不授权新增断点属性。

验证映射

契约 验证 证据证明了什么 缺失的证据
FR1 Section/Layout/Toolbar 渲染和槽位测试 调用方内容在当前区域结构内渲染;Toolbar 暴露其当前车道 测试并未独立证明产品语义仍归调用方所有
FR2 逻辑属性源码审查及 Layout 区域上下文测试 起始/结束槽位按逻辑方式识别,源码选择逻辑分隔线/内边距属性 没有覆盖每个区域的真实浏览器 LTR/RTL 几何矩阵
FR3 Layout.test.tsx 和 childrenAsContent.test.tsx;nestedPadding.test.tsx 以及针对发布几何属性的区域审计规范 槽位存在性/上下文和内容优先级被固定;省略的槽位不会渲染区域提供者 这些测试未断言计算后的外部/内部 inset;nestedPadding.test.tsx 和区域审计规范检查每个区域发布的值
FR4 Section 内边距类集合测试与 Layout 区域源码 Section 的显式边覆盖会移动匹配的变量;区域源码包含自动、显式与零内边距分支 Layout 测试大多断言的是接受性/渲染结果,而非计算后的内边距或自动变量一致性
FR5, FR6 Layout.test.tsx 和 LayoutSlots.test.tsx Header/footer 分隔线默认值以及显式 false 覆盖都会反映在 data-divider 中;源码包含折叠样式 没有任何渲染测试能阻止 LayoutPanel 与相邻 ResizeHandle 同时绘制分隔线,或证明计算后的折叠间距
FR7 LayoutContent/LayoutPanel 源码与本地类/渲染测试 这两个区域暴露了各自的当前 isScrollable 分支;Layout 暴露 fill/auto 状态 没有浏览器测试能证明每种 shell/region 组合中的滚动归属
FR8 LayoutSlots.test.tsx 地标断言 传入的 roles 和 labels 会到达 Header、Content、Footer 和 Panel 元素 没有覆盖重复地标的家族级可访问性树测试
布局内容宽度 contentWidth.test.tsx 和 Storybook 滚动条位置状态 Header/Footer 保留对齐的包装器;无面板的 LayoutContent 拥有全宽滚动区域;任一单面板状态都会通过相对的开放侧镜像内容;两个面板都使组合保持约束 缺少能够验证四个面板状态下计算内容对齐和滚动条位置的真实浏览器证据
工具栏变体 Toolbar.test.tsx Lanes、role/name/orientation、Section 变体委托,以及当前键盘行为都有针对性断言 没有计算 inset/边缘补偿的测试覆盖非默认父级内边距
FR10 LayoutSlots.test.tsx 中的 LayoutPanel 覆盖 Hook 提供的 _size 会覆盖固定的 width prop 调整大小交互、持久化、吸附和折叠仅由 Resizable 自身测试验证

当前测试证明了选定的结构、属性、回调和类/样式分支。它们并未证明每种 Section、Layout、Toolbar 和 ResizeHandle 组合中某一种计算后的视觉对齐;采用表明确列出了这些限制。

DEC-1 — 结构区域与组合原语有各自的所有者

决策者: cixzhang,2026-08-30

Section、Layout 及其命名区域,以及 Toolbar 构成 layout-regions 家族。Stack、Grid、Center 及其修饰符则有独立的 layout-primitives 所有者。这样可以让共享的区域规则聚焦于结构边界,而不会把每个 flex/grid 容器都变成页面区域。

DEC-2 — AppShell 拥有页面外壳

决策者: cixzhang,2026-08-31

AppShell 拥有页面外壳和应用导航组合。Layout 是通用的五插槽原语,用于在页面或有界容器内排列 header、start、content、end 和 footer 区域。更广泛的 container-padding 参与者保留各自的组件所有权。

DEC-3 — 仅内容宽度对齐保留在内容滚动视口内

决策者: cixzhang,2026-09-09

当 contentWidth 在没有面板的情况下设置时,LayoutContent 会横跨可用的中间区域,并通过上下文感知的内联 inset 对齐其直接子元素。当恰好有一个面板时,该面板保持与居中框架对齐,而 LayoutContent 则延伸到相对的开放侧。逻辑上的 start 和 end 相互镜像。当两个面板都存在,或宽度基于百分比、为固有值或未解析的裸变量而无法安全共享同一 CSS 算术基础时,完整的中间组合保持受约束。有保证的长度值变量使用 calc(var(...)) 来选择边缘滚动。

未解决的问题

无。采用情况表包含可检查的源代码和浏览器工作,而非未解决的组件族策略。

内容边界

本记录仅涵盖共享的结构区域行为。它不重复组件属性表,不定义任意子组合,不承担产品或导航语义,不规定视觉设计,不指定响应式断点,不重新定义调整大小的交互,也不拥有组件主题的结构与目标。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx