跳转至

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 容器、其 layout target 以及五个槽位位置。
  • 高度、Layout 边缘内缩量、内容宽度,以及其区域组件所读取的 header 和 footer 分隔线默认值。
  • layout、layout-header、layout-panel、layout-content 和 layout-footer target 的聚合消费者文档和主题映射。

不拥有 / 非目标

  • 页面外壳、应用级导航、响应式外壳替换、跳转链接或主地标 —— 由 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-regions FR8)。
  • AR2 — 逻辑顺序。 插槽按 DOM 顺序渲染:header、start、content、end、footer;start 和 end 遵循书写方向(family:layout-regions FR2)。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
布局容器 将调用者内容放入五个具名插槽中。 当前源码、文档、家族 辅助 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