跳转至

LayoutContent 组件契约

契约一览

方面 契约
公共契约 children、isScrollable、padding、label、role、根 BaseProps 和根 ref。
行为 主内容区域填满 Layout 的中间区域,默认可滚动,并将其子内容与相邻区域和开放边缘隔开。
最终用户影响 用户滚动主内容时,header、footer 和面板保持不动,滚动条位于内容区域的开放边缘。
构建方影响 无:无 API 变更;滚动区域无需代码更改即可获得角色和名称(AR3)。
兼容性/就绪状态 无 API 或默认值变更;滚动区域角色和名称(AR3)是一个补丁 [fix]。没有未关闭的实现差距(当前状态影响)。
审查检查 拒绝围绕子内容的内部包装器、偏离开放边缘的滚动条、推断出的 landmark,或进一步的发布不匹配。
治理规则 family:layout-regions FR1、FR3、FR4、FR7、FR8、FR12;architecture:container-padding;architecture:public-component-api INV5–INV8。

此表是审查投影;下文正文具有权威性。

意图

LayoutContent 是调用方放置在 Layout 的 content 插槽中的主内容区域。它拥有该区域的滚动、内边距(inset)以及调用方提供的 landmark 语义;调用方拥有其内容。

消费者语法和示例属于 LayoutContent.doc.mjs。

兼容性与迁移

  • 已发布默认值保留:yes — 可滚动、自动内边距、无 landmark 角色。
  • 兼容性类别:patch。没有公共 prop、默认值、target 或样式输出变化。滚动时,没有调用方 role 的区域会获得 role="group" 和 aria-label(DOM;AR3,位于 spec:AST-017 FR53 下的 [fix])。
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

当前状态影响

无。除了单个起始面板外,开放的 inline-end 边缘会采用 Layout-edge 内边距,因此 Layout 上的 padding={0} 会使其全出血(full bleed);每个边缘都会发布其应用的内边距,因此全出血的子内容会与 end 面板以及 header 或 footer 对齐,且无需分隔线;每个 Layout 都会清除外部 header 或 footer 的折叠,因此嵌套的 Layout(包括位于 Dialog、Drawer 或 BottomSheet 内部的 Layout)会保持自身的块级间距(FR2)。

所有权边界

拥有

  • 内容根节点,它承载 component:Layout 映射的 layout-content 目标,并且既是滚动容器又是子内容的直接父级。
  • 区域的 inset、滚动以及调用方提供的 role 和 label。

不拥有 / 非目标

  • 插槽放置、Layout-edge 内边距和内容宽度 — 由 component:Layout 拥有。
  • 内容及其含义 — 由调用方拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
滚动 true、false 滚动溢出内容,或裁剪它。 始终 true component:LayoutContent 稳定 —
Inset 间距步长;0;未设置 替代自动 inset 的均匀内边距;0 表示全出血(full bleed)。 始终 automatic component:LayoutContent 稳定 封闭联合类型;被类型拒绝。
Landmark 调用方的 role 和 label 将区域以调用方指定的角色暴露出来,并带有该可访问名称。 始终 none caller 稳定 —

行为与布局契约

ID 不变式 依据
FR1 LayoutContent 渲染一个携带 layout-content 目标的 div,该目标填充中间区域的高度和剩余宽度,并直接持有子元素。默认情况下,它滚动溢出内容;isScrollable={false} 则将其裁剪。 当前源代码与测试;family:layout-regions FR7
FR2 在没有 padding 的情况下,每个面向另一区域(面板、页眉或页脚)的边缘采用内部内边距,每个开放边缘采用布局边缘内边距;其中布局边缘内边距来自 Layout 的 padding,否则来自最近的 padding 容器,而内部内边距来自最近的 padding 容器(Card、Section、Dialog、Drawer 或 BottomSheet),否则每个间距步进为 4;位于没有分隔线的页眉或页脚旁边的块级边缘会折叠为零。padding 步进会替换全部四条边,0 则移除它们。该区域发布的容器 padding 值等于其应用的 padding,但不包括 FR3 的内容宽度对齐沟槽;该沟槽会被应用但不被发布。该折叠仅适用于其旁边放置页眉或页脚的 Layout;嵌套 Layout(包括跨层边界的 Layout)不会继承此行为。 当前源代码与审计记录;family:layout-regions FR4、FR6;architecture:container-padding;spec:AST-038 FR7
FR3 当 Layout 设置内容宽度时,区域保留自己的盒子和滚动条(component:Layout FR6 规定它们的位置),并通过其内联 padding 将子元素对齐到该宽度,且该宽度绝不小于其内边距。使用 padding={0} 时保持全出血。 当前源代码与测试;family:layout-regions FR12
FR4 role 和 label 设置根的 role 和 aria-label;LayoutContent 仅在其滚动时(AR3)添加自身的 role 和名称。 当前源代码与测试;family:layout-regions FR8
FR5 ref 作用于根元素。受支持的 DOM、data、ARIA 和事件 props 会在组件自身属性之后传递到根元素;xstyle、className 和 style 会在组件样式之后合成。 当前源代码与测试;architecture:public-component-api INV5–INV8

允许的变化

  • AV1 — 内容。 任何调用方的内容都可以填充该区域。
  • AV2 — 地标。 调用方决定该区域是否为地标,以及是哪个地标。

代表性状态

状态 必需的不变量 允许的变化
在 Layout 中单独存在 每一边都有 Layout 边缘内边距;可滚动。 内容。
与面板相邻 朝向每个面板的内部内边距。 面板数量。
内容宽度(无面板) 全宽滚动视口;子元素按该宽度对齐。 宽度。
全出血 无内边距;发布的内边距为零。 —
主要地标 根元素上带有 role="main" 和调用方的名称。 名称。

转换与优先级顺序

  • ORD1 — 内边距。 padding → 每条边的自动内边距(朝向区域的内侧、开放边上的 Layout 边缘内边距、在无分隔线的页眉或页脚旁为零);内容宽度对齐只会增加内联内边距。

性能与资源

  • PR1 — 无外部生命周期。 LayoutContent 读取其 Layout 填充哪些插槽。它不会添加任何监听器、观察器、定时器或测量,除非在它可能滚动时进行 AR3 的溢出观察。

可访问性契约

  • AR1 — 仅显式地标。 只有当调用方提供 role 时,该区域才是地标,并且仅由调用方的 label 命名(family:layout-regions FR8)。
  • AR2 — 键盘滚动。 滚动区域是浏览器滚动容器,因此一旦焦点位于其内部或其上,其溢出内容即可通过键盘滚动。
  • AR3 — 滚动区域具有可访问名称。 当区域滚动时,其滚动元素带有 role="group"(除非调用方设置了 role)和一个可访问名称(调用方的 label,或翻译后的“内容”),以便到达该区域的屏幕阅读器(包括作为浏览器生成的 Tab 停留点)能够播报它;Tab 行为由浏览器决定(所有者决定,2026-11-04)。调用方的 role 只会采用调用方的 label 作为名称(AR1),因此单个主地标依赖其 role(spec:AST-025 FR12)。如果浏览器不为其生成 Tab 停留点,那么内容中没有任何可聚焦元素的滚动区域将无法通过键盘滚动。此时调用方需要添加一个可聚焦的子元素,或使用 ScrollableArea。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
内容区域 Layout 的主要滚动区域。 当前源码与文档 突出 FR1–FR3

主题:根元素承载 layout-content 目标,该目标由 Layout.doc.mjs 声明并由 component:Layout 映射。LayoutContent.doc.mjs 本身不声明任何解剖结构,因此此处不声明解剖结构主题块。

家族与系统关系

  • family:layout-regions 负责区域滚动、内边距替换、分隔线间距、地标和内容宽度滚动条放置;FR1–FR4 和 AR1 对这些方面适用。
  • architecture:container-padding 负责内边距发布;FR2 适用于它。
  • component:Layout 负责插槽放置、Layout 边缘内边距、内容宽度以及 layout-content 目标映射。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
------------ ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -----------------------------------
FR1 LayoutSlots.test.tsx class、scroll-owner 和 Layout-slot 测试 单独;在 Layout 中 丢失 layout-content 类、默认不可滚动,或子元素周围出现内部包装器时,测试失败。缺口:isScrollable={false} 和填充尺寸没有检查。 audit:LayoutContent/layout
FR2, ORD1 LayoutSlots.test.tsx 填充测试;LayoutContentAudit.a11y.chromium.spec.ts content-insets 回执 padding={0};数字填充;起始面板;结束面板;无分隔线的页眉;全出血起始面板;嵌套 Layout;RTL 当某个边应用了与预期不同的内边距,或发布了与其所应用的填充不同的值时,审计回执失败。缺口:没有始终运行的检查覆盖自动的逐边内边距、起始面板的 inline-end 内边距、无分隔线的页眉或页脚旁的折叠、嵌套 Layout,或已发布的值;浏览器规范仅针对 LayoutContent 审计拉取请求运行,因此它们只有审计回执,且没有回执覆盖跨图层边界的嵌套 Layout。填充单元测试仅检查区域是否渲染。 audit:LayoutContent/layout
FR3 contentWidth.test.tsx;稳定视觉基线 core-layout--content-width-scrollbar-placement 无面板、一个面板、两个面板;零填充 没有面板时内容区域未占满宽度、子元素未对齐,或全出血丢失,则测试失败;滚动条被移离其边缘后,会以变更后的状态重新出现以供审查。 audit:LayoutContent/layout
FR4, AR1 LayoutSlots.test.tsx 地标测试和 exposes no role or name of its own when it does not scroll;Layout.a11y.test.tsx 和 Layout.a11y.chromium.spec.ts content-main 状态 调用方 main 角色和标签;无调用方角色 丢失角色或名称(包括在无障碍树中丢失)则失败;对于没有调用方 role 且不滚动的区域,出现角色或名称则失败。 audit:LayoutContent/accessibility
FR5 LayoutSlots.test.tsx 中针对 ref、className/style 以及 forwards DOM, data, and event props to the root 行为的测试 Ref、调用方的 class 与 style、DOM、数据和事件属性 如果 ref 被置于另一个元素上,或 class、style、DOM、数据、事件属性之一缺失,则失败。缺口:没有测试固定 xstyle 的合并顺序。 audit:LayoutContent/api
AR2、PR1 源码审查 滚动区域 缺口:没有自动化检查覆盖键盘滚动,也没有在 LayoutContent 添加超出 AR3 范围的监听器或测量时使其失败的检查。 audit:LayoutContent/behavior
AR3 useScrollRegionProps.test.tsx 中的 LayoutContent 测试;scrollRegionName.a11y.chromium.spec.ts 可滚动、可适配、已标记、main、不可滚动 当它溢出时缺少 group 角色或名称,或在它可适配或无法滚动时仍存在 group 角色或名称,均会失败;在 Chromium 的无障碍树中同样如此。丢失调用方的角色或标签、出现默认地标名称或 tab index,也会失败。 audit:LayoutContent/accessibility
RTL 关系 RTL 审计中精选的 D8 目标(apps/storybook/rtl-audit/targets.json),应用于 Content width with start panel 故事 起始面板搭配居中的内容宽度(逻辑内边距:起始 16px,结束 144px);LTR 与 RTL 在 RTL 中,逻辑起始/结束内边距对若未交换物理侧,则 D8 失败。 audit:LayoutContent/i18n-rtl

决策日志

无记录。该记录描述的是已发布的行为。

未决问题

无。

内容边界

本文件不会重复使用方 prop 表格/示例、当前审计结果、实现步骤、Layout 插槽规则或容器内边距机制。它链接到这些内容的所属文档。

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