跳转至

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 → Layout defaultHasDividers → 无。
  • ORD2 — Padding。 padding → 自动 inset。

性能与资源

  • PR1 — 无外部生命周期。 LayoutFooter 从其 Layout 读取分隔线默认值,并且不添加任何监听器、观察器、计时器或测量。

无障碍契约

  • AR1 — 仅显式地标。 仅当调用方提供 role 时,页脚才是地标;并且只通过调用方的 label 命名(family:layout-regions FR8)。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
页脚 一个固定的页脚条带,带有可选的 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