Heading 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个语义化标题,带有必需的 level、可选的、可扩展主题的视觉 type、weight、accessibilityLevel,以及 Heading.doc.mjs 中记录的共享文本控件。 |
| 行为 | level 选择 h1–h6 和默认视觉比例;type 和 weight 只改变外观;accessibilityLevel 在二者不同时设置 aria-level。 |
| 最终用户影响 | 屏幕阅读器用户所浏览的文档大纲与页面各分区一致,而无论每个标题以多大尺寸渲染。 |
| 构建者影响 | 未截断的 Heading 中,长且不间断的 token 会换行。在 flex 行内,flex 子项需要 min-width: 0 才能使换行生效;调用方自身设置 overflow-wrap: anywhere 的容器无法作用于 Heading 的文本;Core 的 anywhere 容器会将换行传递给它。截断 Tooltip 在首次悬停、完成的点击或聚焦时挂载(AR3)。 |
| 兼容性/就绪性 | 已发布行为记录为当前状态,并有一处样式输出变更和一处 DOM 变更:未截断的 Heading 设置 overflow-wrap(break-word,或在 Core 的 anywhere 容器内部为 anywhere)。截断 Tooltip 在首次悬停、完成的点击或聚焦时挂载,因此在此之前,被截断的 Heading 没有 Tooltip 层,也没有 aria-describedby(AR3)。无 API 变更。一项实现差距列于“当前状态影响”之下。 |
| 审查检查 | 拒绝会改变元素或级别的视觉 type 或 weight、渲染时没有级别基线的标题,或用于截断的重复原生 Tooltip。 |
| 治理规则 | spec:AST-024(自定义视觉类型、weight 优先级、无障碍不变);architecture:component-theming-surface/INV6,INV14;architecture:public-component-api/INV5,INV6,INV8。 |
此表为审查投影;下面正文具有权威性。
意图¶
Heading 使用原生标题语义和主题化排印来标记某个分区或页面标题。它将文档大纲(level、accessibilityLevel)与外观(type、weight)分开。其消费者文档位于 Text/Heading.doc.mjs,作为 Text 文档的一部分;本记录是 Heading 自身的契约。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:一处样式输出变更和一处 DOM 变更,无公共 prop 或默认值变更:未截断的 Heading 设置
overflow-wrap(break-word,或在 Core 的anywhere容器内为anywhere),因此长且不间断的 token 会换行(FR3)。截断 Tooltip 在首次悬停、完成的点击或聚焦时挂载(AR3):在此之前,被截断的 Heading 在 DOM 中没有 Tooltip 层,也没有 Tooltip 描述。 - 受控/不受控行为:不适用
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
- 截断 Tooltip 无法通过键盘访问(FR4)。 被截断的 Heading 不可聚焦,因此 Tooltip 无法挂载焦点触发器,有视力的键盘用户无法显示被裁剪的文本,而 WCAG 2.2 2.1.1 要求功能可通过键盘操作。完整文本保留在 DOM 中,供辅助技术使用。
所有权边界¶
拥有
h1–h6元素、其heading主题化目标,以及aria-level。- 基于级别的和内置 display-type 字号、weight 默认值、颜色,以及标题元素上的共享文本布局控件。
- 测量截断,并决定何时组合截断 Tooltip。
不拥有 / 非目标
- 自定义视觉类型的主题注册与生成声明 — 归
spec:AST-024与主题构建所有。 - 非标题文本 — 归
component:Text所有。 - 截断提示气泡的表面、图层与
tooltip目标 — 归 Tooltip 所有。 - 标题内容 — 归调用方所有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 各变体/方向/状态下的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 级别 | 1–6 | 选择 h1–h6 以及该级别的视觉比例。 |
始终 | 必填 | component:Heading |
稳定 | TypeScript 拒绝其他值。 |
| 视觉类型 | display-1、display-2、display-3;主题新增值 |
在不改变语义的前提下取代该级别的视觉比例。 | 始终 | 未设置 | component:Heading |
稳定 | 主题新增的值会反映在 heading 上,并保留该级别的基线(spec:AST-024 FR4)。 |
| 字重 | normal、medium、semibold、bold |
覆盖视觉类型或级别的默认字重。 | 始终 | 视觉类型或级别的默认值 | component:Heading |
稳定 | TypeScript 拒绝其他值。 |
| 无障碍级别 | 1–6 | 暴露给辅助技术的大纲级别。 | 始终 | level |
component:Heading |
稳定 | TypeScript 拒绝其他值。 |
| 截断 | maxLines 0(无)、1 或更多;tooltip 开启、关闭或位于某个位置 |
限制行数并在 Tooltip 中提供完整文本。 | 始终 | 0;tooltip 开启 | component:Heading |
稳定 | — |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | level 渲染为 h1–h6。仅当 accessibilityLevel 与 level 不同时才添加 aria-level。 |
当前源码与测试 |
| FR2 | 标题带有 heading 目标,反映 level、color 以及任何提供的 type 和 weight。内置的 type 应用其显示比例和默认字重;否则应用级别的比例。主题添加的 type 将级别的比例保留为其基线。显式的 weight 优先于 type 和级别的默认值。 |
当前源代码和测试 |
| FR3 | color 默认为 primary;主题添加的 color 在主题为其着色前保持 primary 基线。hasCapsize 渲染 block 并裁剪到帽高;否则,maxLines 大于 1 时渲染 line-clamp 盒子,maxLines={1} 渲染 block,其他情况下应用 display(默认 block)。justify 使用逻辑值;默认为 start,不设置对齐,因此元素跟随其容器的对齐。textWrap 和 hasStrikethrough 应用各自的文本处理。在没有截断的情况下,超过其行的 token 会换行,因此在普通流中,文本不会在 320 CSS px 处强制水平滚动(spec:AST-020 FR1,WCAG 2.2 1.4.10 Reflow)。标题的 overflow-wrap 为 break-word,这保持了 min-content,因此表格和自动调整大小的列按原样排列普通单词;在 Core 容器内部,如果容器用 anywhere 包裹其内容(CommandPaletteEmpty、Toast、FieldStatus、Banner),则标题的 overflow-wrap 也是 anywhere,因为容器自身的文本就是如此。flex 子项需要其容器设置 min-width: 0,而调用方自己的容器设置 overflow-wrap: anywhere 不会影响到标题文本。 |
当前源代码和测试 |
| FR4 | maxLines={1} 用省略号裁剪一行;更大的值会限制到该行数,除非设置了 hasCapsize,其 block 显示会移除该限制。在截断时,wordBreak 默认对于一行为 break-all,否则为 break-word。当文本被测量为已截断且 hasTruncateTooltip 不为 false 时,一个延迟加载的 Tooltip 锚定到标题,在给定位置(默认 above)显示完整文本;不会添加原生 title。hasTruncateTooltip={false} 不进行测量。截断 tooltip 可以通过键盘打开(WCAG 2.2 2.1.1)。实现缺口:tooltip 仅在悬停和触摸时打开,因为标题不可聚焦(当前状态影响)。 |
当前源代码和测试 |
| FR5 | ref 到达标题元素。受支持的 DOM、ARIA、数据和事件 props 在派生出的 aria-level 之后到达它,因此调用方的 aria-level 优先;xstyle、className 和 style 按该顺序在组件样式之后合并,line clamp 在 style 之后应用。 |
当前源代码和测试 |
允许的变体¶
- AV1 — 主题绘制。 主题可以按
level、color、type和weight重新设置heading的样式,而不改变元素或级别。 - AV2 — 视觉复用。 任何级别都可以使用任何视觉类型。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 仅级别 | h{level} 处于该级别的缩放比例。 |
级别。 |
| 显示类型 | 元素相同;显示缩放比例与字重;data-type 得到反映。 |
类型。 |
| 主题新增类型 | 元素相同;级别基线;data-type 得到反映。 |
主题绘制。 |
| 无障碍覆盖 | aria-level 与元素的级别不同。 |
— |
| 带 Tooltip 的截断 | 被截断的标题挂载一个 Tooltip,包含完整文本;在首次悬停、完成的点击或聚焦时挂载。 | 放置。 |
| 截断,Tooltip 关闭 | 标题被截断;不测量;不挂载 Tooltip。 | — |
转换与优先级顺序¶
- ORD1 — 字重。 显式
weight→ 内置类型默认值 → 级别默认值(spec:AST-024FR8)。 - ORD2 — 缩放。 内置
type→ 级别缩放(也是主题新增类型的基线)。 - ORD3 — 显示。
hasCapsize(block) →maxLines大于 1(line-clamp 盒子)→maxLines={1}(block) →display属性。
性能与资源¶
- PR1 — 仅在需要时测量。 仅当
maxLines为正且 Tooltip 启用时才进行截断测量;重新测量跟随尺寸和内容变化,无需每个标题一个观察器;Tooltip 模块仅在文本被截断时加载,Tooltip 本身仅在首次悬停、完成的点击或聚焦时挂载,因此在首次交互之前,一页被截断的文本不会挂载任何关闭的 Tooltip 层。
无障碍契约¶
- AR1 — 原生标题。 元素是原生的
h1–h6;视觉类型或字重绝不会改变角色、级别或名称(spec:AST-024FR15)。 - AR2 — 大纲级别覆盖。
accessibilityLevel通过aria-level暴露不同的大纲级别,而不改变元素。 - AR3 — 截断文本。 完整文本保留在标题的 DOM 中;截断 Tooltip 是唯一的 Tooltip,它添加的任何描述都属于 Tooltip。Tooltip 在首次悬停、完成的点击或聚焦到被截断的标题时挂载,并且该交互会像其已挂载时一样,按照 Tooltip 自身的规则将其打开(Tooltip FR3–FR5);在此之前,标题不携带任何 Tooltip 描述,因为其完整文本已经在其 DOM 中。只有键盘聚焦才算作挂载 Tooltip 的焦点兴趣(
:focus-visible,而不是触摸或触控笔按下带来的焦点);点击也算数并会打开它,包括点击后聚焦到可聚焦子元素的点击,但点击文本输入控件除外,这种点击只会聚焦该控件(Tooltip FR5)。
设计关系¶
| 结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Heading | 按当前层级或类型的比例呈现的区块或页面标题。 | 当前源码与文档 | 突出 | FR1–FR3, AR1, AR2 |
| 截断 Tooltip | 标题被截断时显示的完整文本。 | Tooltip | 辅助 | FR4, AR3 |
主题:标题元素是唯一的 heading 目标。其消费方文档位于 Text/Heading.doc.mjs 中,且未列出任何解剖结构,因此不声明解剖结构主题块;截断 Tooltip 的目标属于 Tooltip。
家族与系统关系¶
spec:AST-024拥有自定义视觉类型、字重优先级,以及视觉变更不改变可访问性的规则;FR2、ORD1 和 AR1 应用该规格。component:Text与 Heading 共用类型样式和截断机制。architecture:component-theming-surface设定了heading目标需遵循的规则(INV6),并将type界定为主题可扩展轴(INV14)。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR2 | Heading.test.tsx 的 level 和 accessibilityLevel 测试 |
级别 1–6;不同覆盖与相等覆盖 | 错误的元素、对于不同覆盖缺少 aria-level,或对于相等覆盖添加了 aria-level,均失败。 |
audit:Heading/a11y |
| FR2 | Heading.test.tsx 的 target、type、主题新增 type、字重和省略 type 测试;extensibleAxes.test.ts;对 AuditMatrix story 运行的 HeadingAudit.a11y.chromium.spec.ts |
展示类型、主题新增 type、字重 | 丢失 heading 类或 data-level、data-color、data-type、data-weight 的反映,反映被省略的 type,或主题新增 type 丢失其级别基线,均失败。展示尺寸顺序错乱,或显式 bold 不比展示默认字重更粗,则浏览器规范失败。缺口:级别比例和级别默认字重没有绘制检查。 |
audit:Heading/theming |
| FR3 | 稳定视觉基线 core-heading--level-1;Heading.stories.tsx;HeadingAudit.a11y.chromium.spec.ts |
级别 1 默认;次要颜色;center 和 end 对齐 |
级别 1 的比例、颜色或展示发生变化时,会以变更状态返回以供审查;justify 未解析为逻辑上的 center 或 end,或标题文本低于其 WCAG 对比度阈值,则浏览器规范失败。缺口:display 优先级、textWrap、字帽高度修剪、删除线以及主题新增颜色基线没有自动化检查。 |
audit:Heading/behavior |
| FR3(重排) | Heading.test.tsx 的长而未断开 Token 测试;TextReflow.a11y.chromium.spec.ts;scripts/text-overflow-wrap-anywhere.test.mjs |
一个长而未断开的 Token,在 320 CSS px 下未截断和单行截断;CommandPaletteEmpty 和 Banner 内部的 Text | 未截断标题中的 Token 不换行,页面在 320 px 下横向滚动,单行截断不再局限于一行,CommandPaletteEmpty 或 Banner 中的 Text 丢失容器的 anywhere 换行或越过行内边缘,或 Core 样式设置了 overflow-wrap: anywhere 但未将其传递给 Text,均失败。 |
audit:Heading/a11y |
| FR4, PR1 | Heading.test.tsx 截断测量测试;useTruncation.test.tsx;HeadingAudit.a11y.chromium.spec.ts |
工具提示开启和关闭;内容变化;单行和双行 | 在工具提示关闭时测量、在开启时未测量,或漏掉重新测量,均失败。单行标题没有省略号、双行钳制未保持两行,或钳制后的标题悬停时不显示全文工具提示,都会使浏览器规范检查失败。差距:wordBreak 默认值和工具提示位置没有自动化检查。 |
audit:Heading/behavior |
| AR3 (工具提示挂载), PR1 | Heading.test.tsx 中“截断工具提示在首次交互时挂载”的用例:任何交互前无工具提示层,首次悬停时出现一个;共享挂载行为由 Text.test.tsx 用例覆盖,因为 Text 和 Heading 共享 TruncationTooltip |
在首次悬停、点击或聚焦之前和之后被截断 | 首次交互前出现工具提示层或描述,或首次悬停、点击或聚焦未按自身规则打开工具提示,均失败。差距:没有对描述进行可访问性树检查(spec:AST-009 FR3)。 |
audit:Heading/a11y |
| FR5 | Heading.test.tsx 的 ref、id、透传、aria-level 优先级、样式输入和行钳制测试 |
重新渲染;id;data-testid;调用方的 aria-level;className、xstyle 和 style |
分离的 ref、丢失的 id 或测试 id、覆盖调用方传入值的派生 aria-level、被丢弃或在组件样式之前合并的 className 或 xstyle,或调用方的 WebkitLineClamp 替换了钳制,均失败。 |
audit:Heading/behavior |
| AR1 | Heading.test.tsx 显示类型元素测试 |
具有 display 和主题添加类型的级别 | 更改元素的视觉类型将失败。 | audit:Heading/a11y |
| AR3 | Heading.test.tsx 截断标题测试;HeadingAudit.a11y.chromium.spec.ts |
截断的标题 | 截断标题上的原生 title 会使两项测试均失败。 |
audit:Heading/a11y |
| AR1, AR2 | HeadingAudit.a11y.chromium.spec.ts 读取 Chromium 的可访问性树(spec:AST-009 FR3) |
级别、相同和不同的覆盖值、显示类型 | 标题以不同于其元素或 aria-level 所需的角色或级别暴露时,会使浏览器规范检查失败。 |
audit:Heading/a11y |
决策日志¶
无记录。
开放问题¶
无。
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实施步骤或家族/系统规则,而是链接到其对应的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx