Layout 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | 五个 ReactNode 槽位(header、start、content、end、footer)、children 作为内容简写、height、padding、contentWidth、defaultHasDividers。 |
| 行为 | Layout 将调用方内容安排到五个命名槽位中,随容器填充或增长,并设置其区域组件使用的内缩量和内容宽度。 |
| 最终用户影响 | 最终用户会在稳定位置看到 header、侧边面板、内容和 footer,这些位置在从右到左的布局中镜像,内容对齐到一种可读宽度。 |
| 构建者影响 | 无;该记录描述的是已发布行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出更改。无未关闭的实现差距(当前状态影响)。 |
| 评审检查 | 拒绝将 target 添加到任意槽位内容、继承父级 Layout padding、内容滚动条移离开放边缘,或可覆盖的 data-height。 |
| 治理规则 | family:layout-regions FR1–FR12;architecture:container-padding;architecture:component-theming-surface;architecture:public-component-api INV5–INV8。 |
此表是评审视图;下方正文具有权威性。
意图¶
Layout 是一个通用布局原语,将五个可选命名槽位 —— header、逻辑起始侧面板、content、逻辑结束侧面板和 footer —— 安排在页面或受限容器内。AppShell 拥有页面外壳。
消费者语法和示例属于 Layout.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes—height="fill",无 padding 覆盖,无内容宽度,分隔线默认值继承。 - 兼容性类别:记录已发布行为;无公开 prop、默认值、DOM、target 或样式输出的更改。
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
无。值为 false、true 或 '' 的槽位(例如当 isOpen 为 false 时的 isOpen && <LayoutHeader />)视同不存在,因此其相邻槽位在该侧采用外侧内缩量;在设置 contentWidth 时,关闭的 start 或 end 槽位与省略该槽位产生相同的 FR6 组合(FR1)。
所有权边界¶
拥有
- Layout 容器、其
layouttarget 以及五个槽位位置。 - 高度、Layout 边缘内缩量、内容宽度,以及其区域组件所读取的 header 和 footer 分隔线默认值。
layout、layout-header、layout-panel、layout-content和layout-footertarget 的聚合消费者文档和主题映射。
不拥有 / 非目标
- 页面外壳、应用级导航、响应式外壳替换、跳转链接或主地标 —— 由 AppShell 拥有。
- 任何槽位中的产品含义或内容 —— 由调用方拥有。
- 区域语义、滚动、内缩量和分隔线 —— 由
component:LayoutHeader、component:LayoutContent、component:LayoutFooter和component:LayoutPanel拥有。 - 调整大小交互 —— 由 useResizable 和 ResizeHandle 拥有。
公开概念¶
| 概念 | 封闭取值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 槽位拓扑 | header、start、content、end、footer |
放置调用方内容;被省略的槽位不渲染任何内容。 | 始终 | 全部省略 | component:Layout |
稳定 | — |
| 内容简写 | children |
当 content 被省略时填充 content 槽位。 |
始终 | 省略 | component:Layout |
稳定 | 两者都给定时 content 优先。 |
| 高度 | fill、auto |
填充容器,或随内容增长。 | 始终 | fill |
component:Layout |
稳定 | 封闭联合;由类型系统拒绝。 |
| Layout 边缘内缩量 | 间距步长;0 |
区域内缩量在 Layout 的外边缘生效;0 表示完全贴边。 |
始终 | 继承或 step 4 | component:Layout |
稳定 | 封闭联合;由类型系统拒绝。 |
| 内容宽度 | 数字(px);CSS 长度字符串 | 每个槽位中对齐内容的宽度。 | 始终 | 无 | component:Layout |
稳定 | — |
| 分隔线默认值 | true、false、未设置 |
LayoutHeader 和 LayoutFooter 子元素的分隔线默认值。 | 始终 | 继承 | component:Layout |
稳定 | — |
行为与布局契约¶
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Layout 渲染一个携带 layout 目标(target)的外部 div,该目标反映 height,并环绕一个内部垂直堆栈:头部插槽、容纳起始插槽的中间行、内容插槽和结束插槽,然后是底部插槽。省略的头部、起始、结束或底部插槽不渲染任何内容;值不可渲染(null、undefined、布尔值或 '')的插槽会缺失,因此相邻区域在该侧采用外部内边距(family:layout-regions FR3),而元素、片段或数组即使渲染为空也算作存在;中间行和内容插槽的填充包装器始终渲染。content 填充内容插槽,当省略 content 时,children 填充它。插槽位置不会向调用者的内容添加任何元素、区域组件或目标。 |
当前源码、文档和测试;family:layout-regions FR1, FR3 |
| FR2 | 外部 div 在四条边上突破父级已发布的容器内边距,内部堆栈先发布零容器内边距,再由其各区域发布各自的内边距。fill(默认值)使 Layout 填充其容器的整个高度,包括已突破的块级内边距;auto 让它随内容增长,至少与其容器同高。 |
当前源码和测试;architecture:container-padding |
| FR3 | padding 设置此 Layout 自身的区域组件在其外边缘应用的内边距;0 为完全出血(full bleed)。嵌套的 Layout 不会继承父级 Layout 的 padding:在没有自己的 padding 时,其区域使用最近的 padding 容器的内边距(Card、Section、Dialog、Drawer 或 BottomSheet),或间距步进 4。每个区域如何应用并发布该内边距由其自身的记录负责(component:LayoutHeader、component:LayoutContent、component:LayoutFooter、component:LayoutPanel)。 |
当前源码、文档和测试;family:layout-regions FR4;architecture:container-padding |
| FR4 | 当调用者提供 LayoutHeader、LayoutContent、LayoutFooter 或 LayoutPanel 时,该组件携带自己的 layout-header、layout-content、layout-footer 或 layout-panel 目标。LayoutPanel 位于逻辑起始、结束或两侧时,是一个 Panel 部件和一个 layout-panel 目标。 |
当前源码、文档和测试;family:layout-regions FR11 |
| FR5 | defaultHasDividers 为 LayoutHeader 和 LayoutFooter 的后代设置分隔线的默认值;显式的 hasDivider 优先,未设置时,嵌套的 Layout 在同一层内继承其父级的默认值;该默认值在 Dialog、Drawer、BottomSheet 或其他层边界处停止(spec:AST-038 FR7),并在 AppShell 根处停止(component:AppShell FR18)。LayoutPanel 不读取该默认值(component:LayoutPanel FR4)。 |
当前源码、文档和测试 |
| FR6 | 使用 contentWidth 且没有面板时,LayoutContent 横跨中间区域,并将其直接子元素对齐到内容宽度,因此其滚动条保持在外部边缘。当恰好有一个面板时,面板保持对齐,而 LayoutContent 延伸穿过相对的开放侧;起始侧和结束侧互为镜像。当有两个面板时,或宽度为百分比(包括带百分比的 CSS 数学函数)、固有宽度或裸变量宽度时,整个中间组合保持受约束;长度取值的变量使用 calc(var(...))。数字以像素为单位。没有 contentWidth 的嵌套 Layout 不会继承其父级的 contentWidth。 |
当前源码、文档和测试;family:layout-regions FR12 |
| FR7 | ref、DOM、data、ARIA 和事件属性、xstyle、className 和 style 会到达或组合在外层 div 上;反射的 data-height 会替换调用方的值。 |
当前源码和测试;architecture:public-component-api INV5–INV8 |
| FR8 | Layout 负责布局重置:一个内部导出项 layoutReset(Core 的 overlayPaddingReset 加上它遗漏的值)在应用它的元素处停止;Layout、其区域组件、Section 以及容器样式发布给后代的所有布局自定义属性都会被重置。它将已发布的容器内边距设置为 0px,并将 Layout 内边距和宽度、flush 值、Section 内边距传播以及容器高度上限设置为 initial。布局根节点会应用它(component:AppShell FR18)。它是内部的,不是主题 API,也不是包导出(architecture:container-padding INV1、architecture:public-component-api INV12)。Core 外部需要相同边界的表面会保留其列表的镜像,并通过针对它的一致性测试进行比对。 |
component:AppShell FR18;architecture:container-padding |
允许的变化¶
- AV1 — 插槽存在性与内容。 任何插槽都可以存在或不存在,并可容纳任意 ReactNode;内容不会因所处位置而成为 Layout 解剖结构的组成部分。
- AV2 — 区域组合。 调用方自行选择提供哪些区域组件;Layout 不会插入它们。
代表性状态¶
| 状态 | 必需不变式 | 允许的变化 |
|---|---|---|
| 仅任意内容 | 根节点上的 layout 目标;插槽内容不会获得目标。 |
内容和高度。 |
| 组合区域 | 每个提供的区域都带有自己的目标。 | 提供哪些区域。 |
| 单面板 | 面板与内容宽度对齐;内容延伸到开放侧。 | 起始侧或结束侧;在 RTL 中镜像。 |
| 双面板 | 整个中间组合被约束在内容宽度内。 | 面板宽度。 |
| 嵌套 Layout | 不继承 Layout 的内边距或内容宽度;分隔线默认值在同一层内继承。 | 其自身的显式值。 |
转换与优先级顺序¶
- ORD1 — 内容插槽。
content→children。 - ORD2 — 内边距。 此 Layout 的
padding→ 外层 Card、Section、Dialog、Drawer 或 BottomSheet 的内边距 → 间距步骤 4;父级 Layout 的内边距从不生效。 - ORD3 — 分隔线默认值。 区域的
hasDivider→ 同一层中最近的defaultHasDividers→ 无分隔线。
性能与资源¶
- PR1 — 无外部生命周期。 Layout 不添加任何监听器、观察器、定时器或测量;内容宽度对齐仅通过 CSS 实现。
无障碍契约¶
- AR1 — 不推断地标。 Layout 不添加任何 role 或 name;地标语义仅来自区域组件由调用者提供的
role和label(family:layout-regionsFR8)。 - AR2 — 逻辑顺序。 插槽按 DOM 顺序渲染:header、start、content、end、footer;start 和 end 遵循书写方向(
family:layout-regionsFR2)。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 布局容器 | 将调用者内容放入五个具名插槽中。 | 当前源码、文档、家族 | 辅助 | FR1、FR2 |
| 页眉 | 可选的由调用者提供的 LayoutHeader。 | 当前源码、文档、家族 | 辅助 | FR4、FR5 |
| 面板 | 位于逻辑起始或结束位置的由调用者提供的 LayoutPanel。 | 当前源码、文档、家族 | 辅助 | FR4、FR5 |
| 内容区域 | 可选的由调用者提供的 LayoutContent。 | 当前源码、文档、家族 | 主要 | FR4、FR6 |
| 页脚 | 可选的由调用者提供的 LayoutFooter。 | 当前源码、文档、家族 | 辅助 | FR4、FR5 |
插槽位置属于拓扑,而非解剖结构。
主题化解剖结构¶
{
"Layout container": {"target": "layout"},
"Header": {"target": "layout-header"},
"Panel": {"target": "layout-panel"},
"Content area": {"target": "layout-content"},
"Footer": {"target": "layout-footer"}
}
面板代表每个 LayoutPanel,无论其位于逻辑起始侧、结束侧还是两侧。
家族与系统关系¶
family:layout-regions负责区域拓扑、逻辑方向、边界、滚动、地标和内容宽度滚动条位置;FR1–FR6 和 AR1–AR2 适用于它。architecture:container-padding负责容器内边距的发布与逃逸;FR2 和 FR3 适用于它。component:LayoutHeader、component:LayoutContent、component:LayoutFooter和component:LayoutPanel分别负责每个区域的行为。architecture:component-theming-surface负责解剖结构和目标映射。architecture:public-component-api负责调用者输入路由;FR7 适用于它。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, ORD1, AV1 | Layout.test.tsx 插槽与内容测试,包括 reports a slot that renders nothing as empty;childrenAsContent.test.tsx;LayoutAudit.a11y.chromium.spec.ts closed-regions 凭据 |
每个插槽;省略的插槽;false、true 和 '' 插槽;content 和 children |
缺少插槽、children 覆盖 content、或将 false、true、'' 插槽报告为已填充都会失败。缺口:省略插槽测试仅检查内容文本,因此为省略插槽渲染的包装器会通过,且没有测试断言插槽内容不会获得任何 target 或元素。闭合区域几何只有审计凭据:浏览器规范仅在 Layout 审计拉取请求时运行。 |
audit:Layout/anatomy |
| FR2 | Layout.test.tsx 高度反射测试;LayoutAudit.a11y.chromium.spec.ts 逃逸边距和零发布凭据 |
fill、auto |
丢失 data-height 反射会失败。缺口:没有始终运行的检查覆盖逃逸边距、零发布或 fill 和 auto 高度;测量这些边距和发布的浏览器规范仅在 Layout 审计拉取请求时运行,因此它们只有审计凭据。 |
audit:Layout/layout |
| FR3, ORD2 | nestedPadding.test.tsx |
位于 AppShell、Card、Section 内部;嵌套的全出血(full-bleed)与带内边距(padded)Layout;显式嵌套内边距 | 嵌套的 Layout 若继承了父级 Layout 的内边距,或丢失了外层 Card 或 Section 的内边距或默认 inset,则测试失败。差距:Layout.test.tsx 中的内边距测试仅断言渲染成功。 |
audit:Layout/layout |
| FR4 | LayoutSlots.test.tsx 类测试;themingTargets.test.ts |
各个区域组件;start 和 end 面板 | 丢失区域目标则失败。 | audit:Layout/theming |
| FR5, ORD3 | Layout.test.tsx 分割线默认值测试,包括 a nested Layout without defaultHasDividers keeps its parent default 和 stops the default at a layer boundary |
默认值为 true;未设置;显式 false;嵌套 Layout;位于 Dialog 内 |
若 header 或 footer 忽略默认值、显式 hasDivider={false} 失效、嵌套 Layout 丢失其父级的默认值,或默认值跨越层边界,则测试失败。 |
audit:Layout/layout |
| FR6 | contentWidth.test.tsx;稳定视觉基线 core-layout--content-width-scrollbar-placement;LayoutContentWidthDefault.a11y.chromium.spec.ts,当没有 contentWidth 的 Layout 在宽于视口的 frame 中将其 header 或 footer 限制在低于 frame 宽度时,该测试失败 |
无面板;仅 start;仅 end;两者都有;零内边距;嵌套;在宽于视口的 frame 中没有 content width | 无面板的内容区域未全宽、双面板中间区域未受约束,或嵌套 Layout 继承了 content width,则测试失败;滚动条移出其内容边缘后,回来时会显示已更改以供审查。关闭的 start 或 end 插槽仅有审计回执(LayoutAudit.a11y.chromium.spec.ts 的 closed-regions,仅在 Layout 审计拉取请求时运行)。 |
audit:Layout/layout |
| FR7 | Layout.test.tsx 的 ref、className、style、透传、事件处理器和自有元数据测试 |
Ref;调用方输入;事件属性;冲突的 data-height |
若 ref 落在另一个元素上、调用方输入或事件处理器丢失,或调用方的 data-height 生效,则测试失败。差距:没有测试固定 xstyle 的合并顺序。 |
audit:Layout/api |
| FR8 | layoutReset.test.tsx,当 Layout 或 Section 写入一个重置未阻止的布局自定义属性时失败,并会在带内边距的 Section 内部读回每个重置值;文档站点的 example-layout-root.test.ts,当文档站点示例根节点的镜像与重置值不一致时失败。 |
Layout 和 Section 写入的每个自定义属性;一个带内边距的 Section 宿主 | 如果某个属性被写入但未重置、某个重置值仍被祖先覆盖、或文档站点镜像与重置值不同,则测试失败。 | audit:Layout/layout |
| AR1, AR2, PR1 | 源码审查 | 每个插槽 | 差距:如果 Layout 添加了角色、重新排列插槽、或添加了监听器或测量,没有任何自动化检查会失败。 | audit:Layout/accessibility |
| 主题化结构映射 | scripts/check-knowledge.mjs |
使用方结构和当前目标 | 缺失、多余或过时的映射会使仓库验证失败。 | audit:Layout/theming |
决策日志¶
DEC-1 — AppShell 拥有页面外壳;Layout 拥有五插槽排列¶
参考: component:Layout/DEC-1
决策者: cixzhang,2026-08-31
AppShell 是页面外壳。Layout 是用于在页面或有界容器内排列 header、start、content、end 和 footer 插槽的通用布局原语。Section、Table、Toolbar 和 Divider 对容器内边距的参与,并不使这些组件成为 Layout 拥有的结构。
开放问题¶
无。
内容边界¶
本文件不会重复使用方 prop 表或示例、组件族区域规则、容器内边距机制、调整大小交互、实现步骤或系统规则。它会链接到这些内容的归属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx