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-017FR53 下的[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-regionsFR8)。 - AR2 — 键盘滚动。 滚动区域是浏览器滚动容器,因此一旦焦点位于其内部或其上,其溢出内容即可通过键盘滚动。
- AR3 — 滚动区域具有可访问名称。 当区域滚动时,其滚动元素带有
role="group"(除非调用方设置了role)和一个可访问名称(调用方的label,或翻译后的“内容”),以便到达该区域的屏幕阅读器(包括作为浏览器生成的 Tab 停留点)能够播报它;Tab 行为由浏览器决定(所有者决定,2026-11-04)。调用方的role只会采用调用方的label作为名称(AR1),因此单个主地标依赖其 role(spec:AST-025FR12)。如果浏览器不为其生成 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