LayoutFooter 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | children, hasDivider, height, padding, label, role、根 BaseProps 和根 ref。 |
| 行为 | 一个不可缩小的 footer 区域,其内部包装器应用并发布 Layout 的 inset,并对齐到 Layout 的内容宽度。 |
| 最终用户影响 | 用户看到 footer 保持其高度位于滚动内容下方,且内容与页面可读宽度对齐。 |
| 构建者影响 | 无;该记录描述的是已发布的行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出更改。没有未解决的实现差距(当前状态影响)。 |
| 审查检查 | 拒绝缩小的 footer、与已应用 padding 不同的已发布 inset、推断的 landmark 或丢失的分隔线默认值。 |
| 管理规则 | family:layout-regions FR1、FR4–FR6、FR8;architecture:container-padding;architecture:public-component-api INV5–INV8。 |
此表为审查投影;下文正文具有权威性。
意图¶
LayoutFooter 是调用方放置在 Layout 的 footer 插槽中的可选 footer 区域。它拥有 footer 的尺寸、inset、分隔线以及调用方提供的 landmark 语义;调用方拥有其内容。
消费者语法和示例位于 LayoutFooter.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes— 除非 Layout 默认值另有规定,否则无分隔线、自动 inset、无 landmark 角色。 - 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM、目标或样式输出更改。
- 受控/不受控行为:不适用
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
无。
所有权边界¶
拥有
- Footer 根元素,它承载
component:Layout映射的layout-footer目标及其内部 padding 包装器。 - Footer 高度、分隔线、inset 以及调用方提供的 role 和 label。
不拥有 / 非目标
- 插槽放置、Layout 边缘 inset、内容宽度和分隔线默认值 — 由
component:Layout拥有。 - Footer 内容及其含义 — 由调用方拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Divider | true, false, unset |
在 footer 的块起始边缘绘制一条线。 | 始终 | Layout 默认值,否则无 | component:LayoutFooter |
稳定 | — |
| Height | number (px); CSS length string; unset | 固定 footer 的块尺寸。 | 始终 | 内容高度 | component:LayoutFooter |
稳定 | — |
| Inset | 间距步长;0;unset |
替换自动 inset 的均匀 padding;0 表示通栏。 |
始终 | 自动 | component:LayoutFooter |
稳定 | 封闭联合;被类型拒绝。 |
| Landmark | 调用方 role 和 label |
将 footer 暴露为调用方命名的 role,并带有该可访问名称。 | 始终 | 无 | 调用方 | 稳定 | — |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | LayoutFooter 渲染一个根 div,承载不会缩小的 layout-footer 目标,围绕一个内部 div,该内部 div 持有 children,其最大宽度为 Layout 的内容宽度,并在根内居中。height 固定根的块尺寸,数字以像素为单位。 |
当前源代码和测试 |
| FR2 | 在没有 padding 时,内部 wrapper 的 inline 和 block-end padding 为 Layout 边缘 inset,其 block-start padding 为内部 inset;其中 Layout 边缘 inset 来自 Layout 的 padding,否则来自最近的 padding 容器;内部 inset 来自最近的 padding 容器(Card、Section、Dialog、Drawer 或 BottomSheet),否则每个间距步进为 4。padding 步进会替换四条边,而 0 会移除它们。该 wrapper 发布的容器 padding 值等于其应用的 padding。 |
当前源代码和测试;family:layout-regions FR4;architecture:container-padding |
| FR3 | 分隔线会在根元素的 block-start 边缘绘制一条 1px 实线,使用 --color-border 颜色,并反映 data-divider="true"。由 hasDivider 决定;未设置时,由同一层中最近的 Layout 的 defaultHasDividers 决定(该默认值在层边界处停止,spec:AST-038 FR7);否则没有分隔线。没有分隔线的页脚会让其上方的中间行折叠其 block-end 间距。折叠会在每个 Layout 处停止,因此嵌套在该中间行中的 Layout(包括从它打开的 Dialog、Drawer 或 BottomSheet 内部的 Layout)会保留自己的间距(spec:AST-038 FR7)。 |
当前源代码和测试;family:layout-regions FR6 |
| FR4 | role 和 label 会设置根的 role 与 aria-label;LayoutFooter 本身不添加任何 role。 |
当前源代码和测试;family:layout-regions FR8 |
| FR5 | ref 可到达根元素。受支持的 DOM、data、ARIA 与事件 props 会到达根元素;xstyle、className 和 style 在组件样式之后组合;被反射的 data-divider 仍归组件所有:调用方的 data-divider 永远不能替换它,因此相邻的间距折叠始终遵循分隔线状态(architecture:public-component-api INV5)。 |
当前源代码和测试;architecture:public-component-api INV5–INV8 |
允许的变化¶
- AV1 — 内容。 任何调用方内容都可以填充页脚。
- AV2 — 地标。 调用方选择页脚是否为地标,以及是哪种地标。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| Layout 中的默认状态 | 自动 inset,无分隔线,无 role。 | 内容。 |
| 带分隔线 | block-start 线条和 data-divider="true"。 |
— |
| 显式 padding | 统一 padding,发布给子级。 | 步进。 |
| Contentinfo 地标 | role="contentinfo" 以及调用方在根上的名称。 |
名称。 |
转换与优先级顺序¶
- ORD1 — 分隔线。
hasDivider→ LayoutdefaultHasDividers→ 无。 - ORD2 — Padding。
padding→ 自动 inset。
性能与资源¶
- PR1 — 无外部生命周期。 LayoutFooter 从其 Layout 读取分隔线默认值,并且不添加任何监听器、观察器、计时器或测量。
无障碍契约¶
- AR1 — 仅显式地标。 仅当调用方提供
role时,页脚才是地标;并且只通过调用方的label命名(family:layout-regionsFR8)。
设计关系¶
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 页脚 | 一个固定的页脚条带,带有可选的 block-start 分隔线。 | 当前源代码和文档 | 支持 | FR1–FR3 |
主题化:根元素携带 layout-footer 目标,该目标由 Layout.doc.mjs 声明并由 component:Layout 映射。LayoutFooter.doc.mjs 本身不声明任何 anatomy,因此此处不声明 anatomy-theming 块。
家族与系统关系¶
family:layout-regions负责区域边界、内边距替换、分隔线间距和地标规则;FR2–FR4 和 AR1 应用这些规则。architecture:container-padding负责内嵌值的发布;FR2 应用它。component:Layout负责插槽放置、Layout 边缘内嵌、内容宽度、分隔线默认值以及layout-footer目标映射。architecture:public-component-api负责调用方输入的转发;FR5 应用它。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | LayoutSlots.test.tsx 中的 class 测试和 applies a numeric height as pixels on the root 测试;contentWidth.test.tsx 中的 LayoutFooter 内层包装器和分隔线测试;headerFooterXstyle.test.tsx 中的 keeps the own styles that xstyle does not set(根元素不收缩) |
默认;数值高度;内容宽度 | 丢失 layout-footer class、缺少像素高度、子节点被放到根元素而非内层包装器上,或分隔线没有位于外部元素上,均会导致失败。页脚根元素收缩也会失败。缺口:内容宽度最大值和居中没有任何检查。 |
audit:LayoutFooter/layout |
| FR2, ORD2 | LayoutHeaderFooterEdges.a11y.browser.spec.ts 中的逐案例内嵌值和发布值 |
自动、显式和零内边距 | 任何边缘上的内嵌值与预期步长不一致(自动、padding、全出血或嵌套 Layout),或发布值与实际应用的内边距不一致,均失败。缺口:从周围的 Card、Section、Dialog、Drawer 或 BottomSheet 取得的自动内嵌没有命名检查;边缘规范在普通框架中渲染每个案例。 |
audit:LayoutFooter/layout |
| FR3, ORD1 | LayoutSlots.test.tsx 和 Layout.test.tsx 中的分隔线测试,包括 an explicit hasDivider={false} on a footer overrides the context default 和 stops the footer default at a layer boundary;LayoutHeaderFooterEdges.a11y.browser.spec.ts 中的线条绘制以及页脚上方内容的折叠,包括在嵌套 Layout 处停止的情况 |
默认;hasDivider;Layout 默认值;显式 false;跨层边界的 Layout 默认值 |
缺少或出现意外的 data-divider、Layout 默认值被忽略、显式 false 失效,或 Layout 默认值跨越层边界,均失败。线条不是 1px solid --color-border、线条没有 data-divider="true",或者页脚上方内容在没有分隔线时未折叠,或越过嵌套 Layout 继续折叠,均失败。 |
audit:LayoutFooter/layout |
| FR4, AR1 | LayoutSlots.test.tsx 中的地标测试和 exposes no role or name without a caller role 测试;Layout.a11y.test.tsx 和 Layout.a11y.chromium.spec.ts 中的 footer-contentinfo 状态 |
调用方 contentinfo 角色和标签;无调用方角色 |
角色或名称丢失会失败,包括在无障碍树中。没有调用方 role 的页脚若暴露了角色或名称,则失败。 |
audit:LayoutFooter/accessibility |
| FR5 | LayoutSlots.test.tsx 中的 ref 测试、passes className, style, DOM, data, and event props to the root 测试和 keeps data-divider when a caller passes its own value 测试;headerFooterXstyle.test.tsx 中的 xstyle 合并顺序测试;LayoutHeaderFooterEdges.a11y.browser.spec.ts 中的 caller-attribute 案例 |
ref;调用方的 class、style、DOM、data 和事件属性;调用方的 data-divider |
ref 出现在其他元素上、调用方属性被丢弃,或调用方的 data-divider 替换或移除了反射值,均失败。xstyle 被页脚自身样式覆盖,或调用方的 data-divider 改变了页脚上方的间距,则失败。 |
audit:LayoutFooter/api |
| PR1 | 源码审查 | 每个状态 | 差距:如果 LayoutFooter 添加了监听器、计时器或测量,没有任何自动化检查会失败。 | audit:LayoutFooter/behavior |
决策日志¶
无记录。该记录描述了已发布行为。
开放问题¶
无。
内容边界¶
此文件不重复使用者 prop 表格/示例、当前审计结果、实现步骤、Layout 插槽规则或容器内边距机制。它会链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx