跳转至

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-024 FR8)。
  • ORD2 — 缩放。 内置 type → 级别缩放(也是主题新增类型的基线)。
  • ORD3 — 显示。 hasCapsize (block) → maxLines 大于 1(line-clamp 盒子)→ maxLines={1} (block) → display 属性。

性能与资源

  • PR1 — 仅在需要时测量。 仅当 maxLines 为正且 Tooltip 启用时才进行截断测量;重新测量跟随尺寸和内容变化,无需每个标题一个观察器;Tooltip 模块仅在文本被截断时加载,Tooltip 本身仅在首次悬停、完成的点击或聚焦时挂载,因此在首次交互之前,一页被截断的文本不会挂载任何关闭的 Tooltip 层。

无障碍契约

  • AR1 — 原生标题。 元素是原生的 h1–h6;视觉类型或字重绝不会改变角色、级别或名称(spec:AST-024 FR15)。
  • 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