FieldLabel 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | FieldLabel 为单个控件或由调用方标记的组渲染可见或视觉隐藏的标签组,支持可选的描述、必填性指示符、图标、工具提示、label 元素 BaseProps 以及 label 元素 ref。 |
| 行为 | 单控件模式使用原生 label;组模式使用带 label 语义的 span。描述会添加一个包装 div,而调用方 props 和 ref 仍保留在内部 label 元素上。描述点击仅转发给一个关联控件。 |
| 最终用户影响 | 用户能够识别控件或组,将辅助文本与名称分开听取,并从完整可见标签区域激活符合条件的控件。信息按钮后的帮助可通过指针、触摸、键盘和屏幕阅读器访问,并且在其上的点按、点击或按键永不改变控件(DEC-1)。 |
| 构建者影响 | 构建者提供稳定的控件 ID 和描述 ID,在标记复合组件时选择组模式,并在受控表面上接入 aria-labelledby 或 aria-describedby。 |
| 兼容性/就绪状态 | 无 API 或默认行为变更;使用 labelTooltip 时,信息触发器是 label 元素之后的 InfoTip 按钮,鼠标点击它不会激活控件(FR9,DEC-1)。组模式渲染 span,而公共类型承诺 label props 和 ref;此项列在“当前状态影响”下。 |
| 审查检查 | 拒绝以下情况:丢失原生/组关联、可访问名称中包含嵌套描述、来自组或交互式描述内容的点击转发、label 元素 props/ref 丢失、工具提示内容隐藏、信息触发器位于 label 元素内部或其按下会激活控件、或存在未记录的公共 prop。 |
| 治理规则 | 既定公共接口;HTML label 语义;WCAG 2.2 SC 2.1.1、SC 4.1.2;component:InfoTip;architecture:public-component-api/INV1,INV5–INV9,INV12;architecture:component-theming-surface/INV3–INV7;spec:AST-020/FR1。 |
此表为审查投影;以下正文具有权威性。
意图¶
FieldLabel 提供 Field 以及 CheckboxInput、Switch 等带标签控件所共用的标签、描述、必填性、图标和工具提示呈现。它仅拥有标签组;关联控件或组拥有值和交互行为。
兼容性与迁移¶
- 默认行为保持不变:是。
- 兼容性类别:无公共 prop、默认行为或导出变更。使用
labelTooltip时,信息触发器从 label 元素内部的图标移至其后的component:InfoTip按钮,二者位于同一行内 flex 行中并排显示;通过任何指针或按键按下它都不会激活控件(FR9,DEC-1)。仅在设置labelTooltip时调用方才会看到该额外包装;其 class、xstyle和 ref 仍保留在 label 元素上(FR6)。 - 受控/非受控行为:不适用。
- 迁移决策:DEC-1 无需调用方更改;ref 类型为 OQ1。
所有权边界¶
拥有
- 原生单控件和非 label 组标签元素的选择。
- 可见和视觉隐藏的标签与描述呈现。
- 来自 FormLayout 必填性上下文的可选/必填异常指示符。
- 针对一个关联控件的安全描述点击转发。
field-label主题目标以及调用方 props、样式和 ref 在 label 元素上的组合。- 可选工具提示触发器是否能够被每种输入模态和辅助技术路径访问和命名。
不拥有 / 非目标
- 关联控件或组的值、禁用语义、焦点模型、键盘行为,以及除标签自身 ID 之外的 ARIA 接线。
- 调用方在标签组周围的布局。
- 信息触发器、其按下切换行为以及工具提示表面,这些委托给
component:InfoTip,并通过其委托给component:Tooltip;FieldLabel 拥有触发器渲染位置、其名称以及其内容被暴露的事实。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 标签模式 | 单一控件;分组 | 选择原生的 <label htmlFor> 或通过 aria-labelledby 引用的 <span>。 |
所有使用场景。 | 单一控件 | component:FieldLabel |
已发布 | 受布尔约束;有关根/引用类型,请参阅 OQ1。 |
| 标签可见性 | 可见;视觉隐藏 | 隐藏时移除标签和描述的布局空间,同时保持其可访问性。 | 两种标签模式皆可。 | 可见 | component:FieldLabel |
已发布 | 受布尔约束。 |
| 可选性标记 | 无;可选;必填 | 显示 FormLayout 表单级可选性默认设置的本地化例外。 | 可见和隐藏标签皆可。 | 无 | component:FieldLabel |
已发布 | 当两个布尔值均为 true 时,“可选”会优先显示;但如果 FormLayout 的默认值是“可选”,则抑制“可选”并显示“必填”。 |
| 前导图标 | 无;图标类型;渲染节点 | 在标签文本之前添加视觉内容。 | 两种标签模式皆可。 | 无 | component:FieldLabel |
已发布 | 通过共享图标插槽渲染。 |
| 说明性提示 | 无;本地化字符串 | 在标签元素之后添加 component:InfoTip;轻点、单击或按键可打开或关闭提示,而不会激活控件 (FR9)。 |
两种标签模式皆可。 | 无 | component:FieldLabel |
已发布 | — |
| 辅助描述 | 无;带有可选显式 ID 的渲染节点 | 将辅助内容与可访问名称分开,并可用于描述。 | 两种标签模式皆可。 | 无 | component:FieldLabel |
已发布 | 缺少 ID 时将关联留给调用方处理。 |
| 描述激活 | 转发;非转发 | 对于单一控件,非交互式描述的点击会模拟原生标签的激活行为。 | 仅单一模式。 | 转发 | component:FieldLabel |
已发布 | 分组模式和交互式后代元素不进行转发。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 单控件模式渲染 <label htmlFor={inputID}>;组模式渲染一个非 label 元素,带有 labelID,供调用方拥有的 aria-labelledby 使用。 |
已确立的公共接口;HTML 和 ARIA 语义 |
| FR2 | 可见和隐藏的标签都保留标签文本;隐藏的标签和描述框保留在无障碍树中,且不占据任何布局空间。 | 已确立的公共接口 |
| FR3 | 描述保持为标签的兄弟元素,因此不会进入控件的可访问名称。非交互式描述的点击会转发到一个符合条件的控件;组标签和交互式后代不会转发激活。 | 已确立的公共接口;原生 label 行为 |
| FR4 | FormLayout 的可选性会抑制匹配的可见标记;在没有表单默认值时,所请求的标记会被本地化并显示。当两个标志都为真时,可选标记优先,但在 FormLayout 默认值为可选的情况下例外:此时可选标记被抑制,必填标记显示。 | 已确立的公共接口和当前测试 |
| FR5 | 标签图标、工具提示锚点、必填/可选文本和描述内容保持源顺序。label 元素使用水平 flex 行;可选的标签/描述包装器使用块级流。使用 labelTooltip 时,一个 inline-flex 行包裹 label 元素及其后跟的 InfoTip(FR9)。所有组件自有的间距都是逻辑的或方向中性的。 |
既定的公共接口和源码观察 |
| FR6 | 已接受的数据、ARIA、DOM、class、style、event 和 xstyle 输入在 label 元素上组合,而不会替换组件自有的目标或关联。当描述渲染时,外层包装器仅用于布局,调用方的 props 仍保留在内层 label 元素上;labelTooltip 行(FR9)同样仅用于布局,因此调用方的 class、xstyle 和 ref 都保留在 label 元素上。 |
architecture:public-component-api/INV5–INV7 |
| FR7 | 公共 ref 和 label 元素 props MUST 描述 FieldLabel 在每种模式下渲染的元素;组模式使用哪个根元素和公共类型组由 OQ1 决定。实现差距:组模式渲染 <span>,而公共 BaseProps 和 ref 类型固定为 HTMLLabelElement。 |
architecture:public-component-api/INV8,INV9;当前运行时/类型 |
| FR8 | 可选工具提示的解释性内容 MUST 可通过键盘访问(WCAG 2.2 SC 2.1.1),其触发器 MUST 具有可访问名称和角色(WCAG 2.2 SC 4.1.2);FR9 的 InfoTip 按钮满足这两点。 | WCAG 2.2 SC 2.1.1、SC 4.1.2;spec:AST-020/FR1 |
| FR9 | 当设置 labelTooltip 时,FieldLabel 会在 label 元素之后且在其外部渲染包含该内容的 component:InfoTip,并将 label 元素和 InfoTip 包裹在同一 inline-flex 行中,就像包裹 label 和 description 一样,因此不会有按钮位于 <label> 内;调用方的 class、xstyle 和 ref 仍保留在 label 元素上,并且仅在设置了 labelTooltip 时才渲染该行。当设置 isLabelHidden 时,InfoTip 与 label 一起视觉隐藏,不留布局槽(FR2),并且在它获得键盘焦点时,该按钮会占据控件上方的流式位置(或在水平标签的标签单元格中),因此它永远不会被遮挡或裁剪(WCAG 2.4.7, 2.4.11);按钮名称是一个包含 label 文本的本地化字符串(如 "About Auto-save")。在信息触发按钮上点按、单击、按 Enter 或空格会打开或关闭 tooltip(component:Tooltip FR9),并且永远不会激活、聚焦或切换关联控件;悬停和聚焦可预览它。 |
DEC-1; HTML label content model; WCAG 2.2 SC 2.1.1, SC 2.4.7, SC 4.1.2 |
允许的变体¶
- AV1 — 父级布局。 Field、CheckboxInput、Switch 及直接消费者可以在不改变其局部语义的情况下安排 label 组的不同布局。
- AV2 — Label 内容。 图标、tooltip、可选性文本和描述内容可以各自独立地不存在。
- AV3 — 控件种类。 描述激活行为遵循关联的原生或自定义控件所支持的点击/焦点行为。
代表性状态¶
| 状态 | 必需不变式 | 允许的变体 |
|---|---|---|
| 单个标签 | 原生 label 关联指向唯一控件。 | 可见或视觉隐藏。 |
| 组标签 | Label 元素不是字面意义上的 label,并且可通过 labelID 被引用。 |
调用方拥有 group 角色和 aria-labelledby。 |
| 描述 | 支持性内容保持在 label 外部,并可暴露 descriptionID。 |
文本或结构化内容。 |
| 可选或必填 | 一个本地化异常标记跟在 label 文本之后。 | 当与 FormLayout 的默认设置一致时被抑制。 |
| 禁用表现 | Label 使用禁用的文本样式且没有指针光标。 | 关联控件拥有实际的禁用状态。 |
| 图标和 tooltip | 共享的 Icon 和 InfoTip 渲染各自拥有的绘制内容;InfoTip 按钮跟随 label 元素,可键盘到达且具有名称,其按下操作绝不会到达控件(FR8, FR9)。 | 两个插槽均可缺失。 |
转换与优先级顺序¶
- ORD1 — 可选性。 FormLayout 的默认设置首先隐藏其对应的标记;当两个本地布尔值都为 true 时,optional 优先。
- ORD2 — Label 元素组合。 组件目标和基础样式先应用,然后才是调用方对 label 元素的
xstyle、class 和内联样式组合;关联和 label 元素的选择仍归组件所有。可选的 description 或labelTooltip行(FR9)会添加布局包装器,但不会重新定向这些输入。
性能与资源¶
- PR1 — 不保留资源。 FieldLabel 不拥有全局监听器、观察器、定时器或外部存储。描述激活复用共享的 input-container hook 与局部 refs;
labelTooltip引入 InfoTip 的(进而 Tooltip 的)监听器和层。
无障碍契约¶
- AR1 — 标签关联。 单个控件使用原生 label 关联;分组控件使用由调用方连接的带标签 span,绝不使用误导性的字面标签。
- AR2 — 描述分离。 描述内容保持在 label 之外,因此不会在无障碍名称中重复,并暴露一个 ID 供调用方持有的
aria-describedby使用。 - AR3 — 隐藏标签。 视觉上隐藏的 label 和描述内容在程序层面仍然可用。
- AR4 — 激活边界。 描述激活绝不会劫持交互型后代元素,也绝不会从分组标签转发到单个控件。
- AR5 — Tooltip 可达性。 Tooltip 内容 MUST 可通过键盘 (WCAG 2.2 SC 2.1.1)经由命名触发器(SC 4.1.2)——即跟随 label 的 InfoTip 按钮 (FR8、FR9)——到达。
设计关系¶
当前仓库中没有设计记录约束组件局部的视觉调整。实现使用共享的语义类型、颜色、间距和禁用 token;渲染证据记录最终状态,但不将其确立为规范。
家族与系统关系¶
architecture:public-component-api负责导出、label 元素 prop 组合、ref 准确性以及已发布 API 兼容性。architecture:component-theming-surface负责 anatomy 到 target 的布置以及 target 组合。architecture:component-test-sufficiency负责为每个关键且已确立的公共接缝提供有界且对变异敏感的证据。
验证映射¶
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR3, AR1–AR4 | FieldLabel.test.tsx 关联、ref 和描述转发用例;FieldLabelAudit.a11y.chromium.spec.ts 默认、自定义主题、RTL 以及窄宽度下的浅色和深色用例 |
单个、分组、描述、交互式描述子元素 | 错误的 label 元素、关联丢失、嵌套描述,或转发的分组或交互式点击会失败。证据缺口:没有测试断言隐藏的 label 和描述不留任何布局槽位。 | audit:FieldLabel/accessibility |
| FR4, ORD1 | FieldLabel.test.tsx 可选、必填、两者同时设置以及 i18n 用例;FormLayout.test.tsx 通过 Field 的默认可选性用例 |
可选、必填、两者、本地化 | 错误的本地化标记、必填优先于可选,或与表单默认值重复的标记会失败。 | audit:FieldLabel/behavior |
| FR5 | FieldLabel.test.tsx label 图标、信息按钮位置以及带可选性的 tooltip 用例 |
图标、tooltip、可选性 | 缺少图标或 tooltip 锚点会失败。证据缺口:没有测试断言源代码顺序、flex 行或逻辑间距。 | audit:FieldLabel/layout |
| FR6, ORD2 | FieldLabel.test.tsx 中的 ref、layout-item 和 label-target 用例;themingTargets.test.ts |
Ref;复合目标;带描述包装器 | ref 丢失或 field-label 目标缺失会导致失败;渲染出的类名不在文档化目标中也会导致失败。证据缺口:没有测试断言调用方的 class、style、xstyle、data 和事件属性会应用到带描述包装器或 labelTooltip 行的内部标签元素上。 |
audit:FieldLabel/api |
| FR7 | 证据缺口:没有类型测试将公共 ref 和 props 与渲染出的 group span 进行对照验证 | — | — | audit:FieldLabel/api |
| FR8, AR5 | FieldLabelAudit.a11y.chromium.spec.ts 工具提示锚点计数 |
存在工具提示 | 审计断言在标签元素之后且在其外部存在一个命名的、可聚焦的 InfoTip 按钮;匿名、不可聚焦或嵌套在标签内部的触发器会导致失败。 | audit:FieldLabel/accessibility |
| FR9 | FieldLabel.test.tsx 中的信息按钮位置和名称、隐藏标签的 Tab 停靠点、手指点按、触控笔点按、鼠标点击和空格键复选框用例,以及 Switch 标签点击用例;FieldLabelTap.a11y.chromium.spec.ts 中的触摸点按、鼠标点击和 Enter 文本字段用例,以及隐藏标签的聚焦按钮位于字段上方的情况;证据缺口:没有检查测量隐藏标签的按钮是否不占据布局空间 |
复选框、文本字段和 Switch 标签;手指、触控笔、鼠标、Enter 和空格键;isLabelHidden 且键盘焦点位于 InfoTip 上 |
若出现以下情况则失败:对信息触发器的点按、点击或按键操作激活、聚焦或切换了控件;信息按钮位于标签元素内部;触发器名称中不包含标签文本;或隐藏标签的 InfoTip 占据布局空间或在聚焦时保持不可见。 | audit:FieldLabel/accessibility |
| PR1 | 证据缺口:没有测试断言不存在保留的资源 | — | — | audit:FieldLabel/code-health |
| 文档 | docPropLiterals.test.ts;docPropReferences.test.ts |
已记录的 props 与默认值 | 已记录的字面量或 prop 引用若偏离源类型,则失败。 | audit:FieldLabel/docs |
| RTL 适用性 | apps/storybook/rtl-audit/verified-not-applicable.json 中关于 core/FieldLabel 的条目 |
已签入的 FieldLabel stories | 某个 story 若获得方向性布局或行为,会使 not-applicable 条目失效。 | audit:FieldLabel/i18n-rtl |
当前状态影响¶
- 分组模式类型(FR7)。 分组模式渲染
<span>,而公共 props 和 ref 却按HTMLLabelElement进行类型定义,这与architecture:public-component-api的 INV8 和 INV9 相悖;修复方案为 OQ1。
决策日志¶
- DEC-1 — 按下信息触发器用于获取其帮助。 在标签的信息触发器上进行触摸、点击、Enter 或 Space 操作会打开或关闭帮助,且绝不会激活标签的控件;因此,无论使用何种指针或按键,询问某个设置的作用都不会切换开关或聚焦字段。触发器为
component:InfoTip,即 Tooltip 按压切换之上的信息图标预设,位于标签元素之后;因为<label>除其所标注的控件外,不得包含其他控件。已否决:将触摸或鼠标点击留给标签本身。
标签元素与 ref 的类型定义为 OQ1。
开放问题¶
- OQ1 —
isGroupLabel是否应暴露一个可辨识的 span 根 BaseProps/ref 契约,还是 FieldLabel 应使用一个在两种模式下公共类型均稳定的根元素?(human-api)
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx