跳转至

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-regions FR8)。

设计关系

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