LayoutHeader 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | children、hasDivider、height、padding、paddingBlockEnd、label、role、根 BaseProps 和根 ref。 |
| 行为 | 一个不收缩的头部区域,其内部包装器应用并发布 Layout 的内边距,并对齐到 Layout 的内容宽度。 |
| 最终用户影响 | 用户会看到头部保持在滚动内容上方并维持其高度,内容对齐到页面的可读宽度。 |
| 构建者影响 | 无;该记录描述的是已发布行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出变更。没有未解决的实现差距(当前状态影响)。 |
| 审查检查 | 拒绝收缩的头部、与已应用内边距不一致的已发布 inset、被推断出的地标,或丢失的分隔线默认值。 |
| 治理规则 | family:layout-regions FR1、FR4–FR6、FR8;architecture:container-padding;architecture:public-component-api INV5–INV8。 |
此表是审查概览;下文正文为准。
意图¶
LayoutHeader 是调用方放在 Layout 的 header 插槽中的可选头部区域。它负责头部的大小、inset、分隔线以及调用方提供的地标语义;调用方负责其内容。
使用方语法和示例属于 LayoutHeader.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes— 除非 Layout 默认值另有说明,否则无分隔线;自动 inset;无地标角色。 - 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM、目标或样式输出变更。
- 受控/非受控行为:不适用
- 迁移决策:无
使用方迁移说明属于使用方文档和发布说明。
当前状态影响¶
无。
所有权边界¶
拥有
- 头部根元素,它承载
component:Layout映射的layout-header目标,以及其内部内边距包装器。 - 头部高度、分隔线、inset,以及调用方提供的 role 和 label。
不拥有 / 非目标
- 插槽位置、Layout 边缘 inset、内容宽度和分隔线默认值 — 由
component:Layout拥有。 - 头部内容及其含义 — 由调用方拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 分隔线 | true、false、unset |
在头部的 block-end 边缘绘制一条线。 | 始终 | Layout 默认值,否则无 | component:LayoutHeader |
稳定 | — |
| 高度 | number(px);CSS 长度字符串;unset | 固定头部的块尺寸(block size)。 | 始终 | 内容高度 | component:LayoutHeader |
稳定 | — |
| 内边距 | 间距步进;0;unset |
替换自动 inset 的均匀内边距;0 为完全出血(full bleed)。 |
始终 | 自动 | component:LayoutHeader |
稳定 | 封闭联合;由类型系统拒绝。 |
| Block-end 内边距 | 间距步进;unset | 仅替换 block-end 内边距。 | 始终 | 自动 | component:LayoutHeader |
稳定 | 封闭联合;由类型系统拒绝。 |
| 地标 | 调用方的 role 和 label |
将头部暴露为调用方命名的 role,并带有该可访问名称。 | 始终 | 无 | 调用方 | 稳定 | — |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | LayoutHeader 渲染一个根 div,带有 layout-header 目标,不会收缩;内部包含一个持有 children 的 div,其最大宽度为 Layout 的内容宽度,并在根元素内居中。height 固定根元素的块级尺寸,数字以像素为单位。 |
当前源代码和测试 |
| FR2 | 在没有 padding 时,内部包装器的内联和块首(block-start)内边距为 Layout 边缘缩进,其块末(block-end)内边距为内部缩进;其中 Layout 边缘缩进来自 Layout 的 padding,否则来自最近的 padding 容器;内部缩进来自最近的 padding 容器(Card、Section、Dialog、Drawer 或 BottomSheet),否则每个间距步进为 4。padding 步骤会替换四条边,0 则移除它们。paddingBlockEnd 仅替换块末边缘。该包装器发布的 container-padding 值等于其应用的内边距。 |
当前源代码和测试;family:layout-regions FR4;architecture:container-padding |
| FR3 | 分隔线会在根元素的块末边缘绘制一条 1px 实线 --color-border,并反映 data-divider="true"。是否显示由 hasDivider 决定;当未设置时,由同一层中最近的 Layout 的 defaultHasDividers 决定(默认行为在层边界处停止,spec:AST-038 FR7);否则不显示分隔线。没有分隔线的头部会使其下方中间行折叠其块首(block-start)间距。折叠在每个 Layout 处停止,因此嵌套在该中间行中的 Layout(包括从它打开的 Dialog、Drawer 或 BottomSheet 内部)会保留自身的间距(spec:AST-038 FR7)。 |
当前源代码和测试;family:layout-regions FR6 |
| FR4 | role 和 label 设置根元素的 role 和 aria-label;LayoutHeader 本身不添加任何 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 中的默认状态 | 自动缩进,无分隔线,无 role。 | 内容。 |
| 带分隔线 | 块末边缘的线条和 data-divider="true"。 |
— |
| 显式 padding | 统一 padding,发布给 children。 | 步进。 |
paddingBlockEnd |
仅块末边缘发生变化。 | 步进。 |
| Banner 地标 | 根元素上的 role="banner" 和调用方的名称。 |
名称。 |
转换与优先级顺序¶
- ORD1 — 分隔线。
hasDivider→ Layout 的defaultHasDividers→ 无。 - ORD2 — Padding。 块末使用
paddingBlockEnd→padding→ 自动缩进。
性能与资源¶
- PR1 — 无外部生命周期。 LayoutHeader 从其 Layout 读取分隔线默认值,不添加任何监听器、观察器、定时器或测量。
无障碍契约¶
- AR1 —— 仅显式地标。 页眉仅在调用方提供
role时才成为地标,并且只能通过调用方的label命名(family:layout-regionsFR8)。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 页眉 | 固定页眉带,带有可选的 block-end 分隔线。 | 当前源码与文档 | 支撑 | FR1–FR3 |
主题:根元素承载 layout-header 目标;该目标由 Layout.doc.mjs 声明并由 component:Layout 映射。LayoutHeader.doc.mjs 未声明自身的解剖结构,因此此处不声明任何解剖结构主题块。
家族与系统关系¶
family:layout-regions负责区域边界、内边距替换、分隔线间距和地标规则;FR2–FR4 和 AR1 适用之。architecture:container-padding负责内边距发布;FR2 适用之。component:Layout负责插槽位置、Layout 边缘内边距、内容宽度、分隔线默认值和layout-header目标映射。architecture:public-component-api负责调用方输入路由;FR5 适用之。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | LayoutSlots.test.tsx 的 class、高度和 inner-wrapper 测试;contentWidth.test.tsx 的 LayoutHeader inner-wrapper 和分隔线测试;headerFooterXstyle.test.tsx 的 keeps the own styles that xstyle does not set(非收缩根元素) |
默认;数值高度 | 丢失 layout-header class、缺少像素高度、子元素直接放置于根元素上,或分隔线脱离外部元素,均失败。页眉根元素发生收缩则失败。缺口:内容宽度上限与居中没有任何检查。 |
audit:LayoutHeader/layout |
| FR2, ORD2 | Layout.test.tsx 的 paddingBlockEnd 测试;LayoutHeaderFooterEdges.a11y.browser.spec.ts 的逐用例内边距和发布值 |
单独使用 paddingBlockEnd,以及配合 padding 使用 |
若 paddingBlockEnd 未添加 class、改动超过 block-end 边缘,或脱离了共享的逐边缘家族,则失败。若任一边缘(自动、padding、全出血或嵌套 Layout)上的内边距与预期步长不一致,或发布值与实际应用的 padding 不一致,则失败。缺口:从周围 Card、Section、Dialog、Drawer 或 BottomSheet 获取的自动内边距没有具名检查;边缘规范在普通框架中渲染每个用例。 |
audit:LayoutHeader/layout |
| FR3, ORD1 | LayoutSlots.test.tsx 和 Layout.test.tsx 的分隔线测试,包括 stops the default at a layer boundary;LayoutHeaderFooterEdges.a11y.browser.spec.ts 的线条绘制,以及页眉下方内容的折叠,包括在嵌套 Layout 处停止的情况 |
默认;hasDivider;Layout 默认值;显式 false |
丢失或出现意外的 data-divider、Layout 默认值被忽略,或显式 false 丢失,均失败。线条不是 1px solid --color-border、线条没有 data-divider="true"、页眉下方内容在没有分隔线时未折叠,或折叠越过嵌套 Layout,均失败。 |
audit:LayoutHeader/layout |
| FR4, AR1 | LayoutSlots.test.tsx 的地标测试和 exposes no role or name without a caller role 测试;Layout.a11y.test.tsx 与 Layout.a11y.chromium.spec.ts 的 header-banner 状态 |
调用方提供 banner role 和 label;无调用方 role |
丢失 role 或 name 则失败,包括在无障碍树中的失败。没有调用方 role 的页眉若暴露 role 或 name,则失败。 |
audit:LayoutHeader/accessibility |
| FR5 | LayoutSlots.test.tsx 的 ref、className、passes 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 和事件 props;调用方的 data-divider |
如果 ref 指向另一个元素、调用方的 class 或 prop 被丢弃,或者调用方的 data-divider 替换或移除了反射值,则测试失败。如果 xstyle 被 header 自身的样式覆盖,或者调用方的 data-divider 改变了 header 下方的间距,则测试失败。 |
audit:LayoutHeader/api |
| PR1 | 源代码审查 | 所有状态 | 缺口:如果 LayoutHeader 添加了监听器、定时器或测量逻辑,没有任何自动化检查会失败。 | audit:LayoutHeader/behavior |
决策日志¶
未记录任何决策。此记录描述的是已发布行为。
待解决问题¶
无。
内容边界¶
本文件不会重复使用方 prop 表格/示例、当前审计结果、实现步骤、Layout 插槽规则或容器内边距机制。它会链接到各自的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx