RadioList 组件契约¶
契约一览¶
| 方面 | 契约 |
|---|---|
| 公共契约 | 无变更。RadioList 接受 label、value、onChange、orientation、size、isDisabled、disabledMessage、isRequired、isOptional、status、htmlName、Field props、part props 以及 RadioListItem 子项。 |
| 行为 | 由 Field 提供标签、共享同一名称的原生单选按钮组成的 role="radiogroup"。选择一个选项会调用 onChange(value)。该组设置项尺寸、禁用状态和必填语义。 |
| 最终用户影响 | 用户通过指针、触摸或浏览器箭头键选择一个选项,并拥有可预测的第一个 Tab 停靠点。没有原因的禁用组会脱离 Tab 顺序,因此键盘用户无法找到它。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已交付行为;无 API、默认值或 DOM 变更。禁用单选按钮上的原生 disabled 与 spec:AST-085 FR1 和 FR7 冲突;列于当前状态影响之下。 |
| 审查检查 | 拒绝:没有名称的组、失去共享名称的单选按钮、禁用状态下的选择、落在组中间且值为空的第一个 Tab 停靠点,或根样式 props。 |
| 治理规则 | family:input-fields FR10、DEC-7;spec:AST-085 FR1–FR7;design:user-states DR1、DR2(通过 RadioListItem);WAI-ARIA 单选组模式。 |
此表是供审查的速览;以下正文才是权威内容。
意图¶
RadioList 将一组相互排斥的选项呈现为单个带标签的单选组。它负责管理该组的名称、所选值、共享单选名称、组级禁用、必填和状态语义,以及进入时的 Tab 停靠点。每个选项都是一个 component:RadioListItem。消费者用法见 RadioList.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes;orientation="vertical"、size="md"、未禁用 - 兼容性类别:记录已交付行为;无公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:仅受控;
value为必填,''表示未选择任何项 - 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
- 组 Field 和
role="radiogroup"元素、其名称、描述、状态、无效与必填状态,以及radio-list目标。 - 共享单选名称、所选值以及
onChange。 - 组禁用状态以及组禁用原因提示框(tooltip)。
- 未选择任何项时的进入 Tab 停靠点。
- base、
container*和control*props 所归属的位置。
不拥有 / 非目标
- 每个选项的单选按钮、命名、描述、行、禁用项状态以及
radio-list-item目标——由component:RadioListItem拥有。 - 箭头键在单选按钮之间的移动和选择——由浏览器原生的单选组行为处理。
- 单选指示器——由 Indicator 注册表中的单选指示器拥有。
- 组标签和状态消息的呈现——由
family:input-fields(共享拥有者部分)下的 Field 和component:FieldStatus拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 值 | string;'' 表示无 |
所选选项的值。 | 始终可用。 | 必填 | component:RadioList |
稳定 | 没有任何项携带该值时,则不会选中任何项。 |
| 方向 | vertical、horizontal |
选项的布局。 | 始终可用。 | vertical |
component:RadioList |
稳定 | TypeScript 拒绝其他值。 |
| 尺寸 | sm、md |
每个项的单选圆圈大小。 | 始终可用。 | md |
component:RadioList |
稳定 | TypeScript 拒绝其他值。 |
| 禁用 | 关、开、带原因的开 | 阻止每个项上的选择。 | 仅在 isDisabled 时应用原因。 |
关 | component:RadioList |
稳定 | 没有 isDisabled 的原因不会渲染任何内容。 |
| 状态 | error、warning、success、可选消息 |
组验证状态。 | 始终可用;消息是分离的。 | 无 | family:input-fields |
稳定 | TypeScript 拒绝其他类型。 |
| 名称 | string | 共享单选 name 和表单字段名称。 |
始终可用。 | 生成的 id | component:RadioList |
稳定 | 不适用。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | RadioList 在组标签模式下渲染一个 Field(标签渲染为 span,除非 isLabelHidden 否则可见,包含描述、可选或必填标记、标签工具提示、脱离状态),并围绕一个 role="radiogroup" 元素。该 radiogroup 由组标签以及任何调用方提供的 aria-labelledby 标记,并由调用方提供的任何描述,以及现存的描述、状态消息和禁用原因来描述。 |
WAI-ARIA 单选组模式;当前测试 |
| FR2 | 每个条目的单选按钮共享同一个 name:若提供了 htmlName 则使用它,否则使用生成的 id,从而使这些单选按钮构成一个原生组。被选中的单选按钮是其 value 等于组 value 的那个。 |
当前测试 |
| FR3 | 选择启用的选项时,会调用一次 onChange(value);RadioList 本身不持有任何选中状态。 |
当前测试 |
| FR4 | 当 value 为空时,键盘焦点进入该组会落在第一个未被原生禁用的单选按钮上(在带原因而被禁用的组中,即为第一个 aria-disabled 单选按钮,在 spec:AST-085 FR1 下保持启用的焦点顺序),当从后向前进入时则停留在最后一个上。焦点在组内单选按钮之间移动时不会被重定向。存在选中项时,选中的单选按钮是 Tab 停留点。方向键遵循浏览器原生的单选按钮行为,该行为会在 aria-disabled 单选按钮上停止。 |
WAI-ARIA 单选组模式;当前测试 |
| FR5 | isDisabled MUST 禁用每个条目:每个单选按钮保持可通过 aria-disabled="true" 聚焦,并与表单脱离,因此不会提交,同时拒绝选择(spec:AST-085 FR1–FR3、FR7)。radiogroup 元素 MUST 带有 aria-disabled="true",如同 component:ButtonGroup FR1 所做的那样。启用 disabledMessage 时,原因工具提示还会在组悬停和键盘聚焦时打开,并且该原因 MUST 描述每个可聚焦的单选按钮(spec:AST-085 FR5、FR7)。实现差距:原因仅描述 radiogroup,因此被聚焦的单选按钮不会由它描述;且没有 disabledMessage 时,每个单选按钮会改用原生的 disabled,这会将其从 Tab 顺序中移除,当组变为禁用时,已聚焦的单选按钮也会失去焦点(spec:AST-085 FR4)。 |
spec:AST-085 FR1–FR5, FR7;当前测试 |
| FR6 | status.type === 'error' 会在 radiogroup 上设置 aria-invalid。radiogroup 通过 aria-required 暴露有效的必填状态(包括表单级默认值),而每个 radio 的原生 required 仅遵循显式的 isRequired;原生必填的 radio 的 aria-invalid 遵循相同的状态,因此浏览器自身的无效状态绝不会在出错前显示。 |
当前源代码和测试 |
| FR7 | radiogroup 以较小间距的列排列选项,或在水平方向时以较宽间距的行排列,并将 size 传递给每个选项。 |
当前源代码和测试 |
| FR8 | 基础 props(ref、id、aria-*、data-*、hidden、inert、dir、DOM 事件处理器)会传递到 radiogroup;调用方的 onFocus 在 FR4 的进入处理之后运行。container* 会传递到渲染处的 Field box(在 horizontal-labels FormLayout 中不会渲染任何内容,且 container* 无效果并发出警告),而 control* 传递到 radiogroup;根级 xstyle、className 和 style 不被接受。 |
family:input-fields FR10;当前测试 |
| FR9 | radiogroup 带有 astryx-radio-list,并反映 data-orientation 和 data-size。 |
architecture:component-theming-surface;当前测试 |
允许的变体¶
- AV1 — 选项。 项内容在
component:RadioListItem下可以变化。 - AV2 — 主题绘制。 主题可以通过
radio-list重新设置该组的样式。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
| 空值 | 向前 Tab 进入第一个非原生禁用的 radio。 | 方向。 |
| 已选中一项 | 选中的 radio 处于选中状态,并且是 Tab 停留点。 | 尺寸。 |
| 错误状态 | aria-invalid;独立的消息描述该组。 |
消息。 |
| 禁用(含原因) | 单选按钮可获得焦点、拒绝选择、不提交;原因工具提示。实现差距:调用方的 onClick 仍会运行(RadioListItem FR6)。 |
— |
| 禁用(无原因) | 与含原因的情况相同,但没有工具提示。实现差距:原生 disabled(FR5)。 |
— |
转换与优先级顺序¶
- ORD1 — 项目可用性。 组禁用或项目禁用;组原因仅使组禁用的单选按钮保持可聚焦。
- ORD2 — 必填。 radiogroup 上的有效必填;每个单选按钮上的显式必填。
性能与资源¶
- PR1 — 进入处理。 FR4 仅在
value为空的焦点事件上运行,且不添加全局监听器。
无障碍契约¶
- AR1 — 组语义。
role="radiogroup"带有名称、描述、无效和必填状态(FR1、FR6)。 - AR2 — 键盘。 Tab 一次到达组(FR4);方向键通过原生单选按钮行为移动和选择。
- AR3 — 禁用原因。 组原因保持可通过键盘焦点和辅助技术到达(FR5)。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 组标签 | 选项上方的字段组标签。 | 当前来源 | 突出 | FR1 |
| 选项 | RadioListItem 行的列或行。 | 当前来源 | 突出 | FR7 |
| 状态消息 | 组之后的独立消息。 | 当前来源 | 辅助 | FR1、FR6 |
design:user-states 控制其选项绘制的按下覆盖层(component:RadioListItem FR8);没有其他设计记录控制 RadioList。radiogroup 带有 radio-list。
家族与系统关系¶
spec:AST-085负责禁用原因;family:input-fieldsFR10 和 DEC-7 负责 prop 目标;RadioList 满足 FR10。spec:AST-085负责禁用可聚焦性;FR5 记录了该差距。component:RadioListItem负责每个选项,并通过上下文读取该组。
验证映射¶
| 契约 | 验证 | 代表状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, AR1 | RadioList.test.tsx 中的标签、span-label、hidden-label、必填与可选标记、状态和组描述用例;RadioGroup.a11y.test.tsx 和 RadioGroup.a11y.chromium.spec.ts |
可见和隐藏标签;每种状态;描述 | 缺少组名称或描述则失败。证据缺口:没有测试断言调用方描述在前、禁用原因在后,或标签工具提示。 | audit:RadioList/accessibility |
| FR2, FR3 | RadioList.test.tsx 选择和表单用例 |
单选按钮、标签和描述的点击;htmlName;无名称 |
错误的值、丢失分组、错误的表单值,或单击单选按钮时触发第二次 onChange,均失败。证据缺口:没有测试统计委托的标签和描述点击上的 onChange 调用次数。 |
audit:RadioList/behavior |
| FR4, AR2, PR1 | RadioList.test.tsx 焦点管理用例;RadioGroup.a11y.chromium.spec.ts 中每个 radio-list-group-* 状态上的 radio-group.focus.entry-and-exit 规则 |
向后进入;组内移动;禁用单选按钮 | 被重定向的组内移动、进入原生禁用的单选按钮,或 Tab 进入点不是选中项或第一项,均失败。证据缺口:没有测试进入带原因禁用的空组,也没有测试在进入处理之后断言调用方 onFocus,或断言没有全局监听器。 |
audit:RadioList/accessibility |
| FR5, ORD1, AR3 | RadioList.test.tsx 中的禁用用例(包括 radiogroup 的 aria-disabled)、disabledMessage 用例和表单用例;ListGroupDisabled.a11y.chromium.spec.ts;RadioGroup.a11y.test.tsx 和 RadioGroup.a11y.chromium.spec.ts 的 radio-list-group-disabled-with-message 与 radio-list-option-group-disabled 状态 |
组和项禁用;带原因 | 禁用状态下进行选择,或从带原因禁用的组提交值,都会失败;该绑定期望 radio-list-option-group-disabled 的 tabReachable: false,当该差距被填补时即失败。证据缺口:没有表单用例提交项禁用选项或未带原因禁用的组,也没有测试在单选按钮聚焦时禁用组。 |
audit:RadioList/accessibility |
| FR6, ORD2 | RadioGroup.a11y.test.tsx 和 RadioGroup.a11y.chromium.spec.ts 的 radio-list-group-required-invalid-described 状态 |
必填、无效、带描述说明的组 | 组上缺少必填或无效状态将导致失败。证据缺口:没有测试断言表单级必填默认值只会反映到 aria-required 上。 |
audit:RadioList/accessibility |
| FR7, FR9 | RadioList.test.tsx 的 theme-target 用例 |
size="sm" |
缺少行尺寸则失败。证据缺口:orientation 用例仅断言渲染;没有测试断言 radiogroup 上的间距、水平布局、data-orientation、data-size 或 astryx-radio-list。 |
audit:RadioList/layout |
| FR8 | RadioList.fr10.test.tsx;RadioList.test.tsx 的 data-testid 用例 |
调用方 labelledby;hidden、inert、dir;horizontal-labels FormLayout |
base prop 不在 radiogroup 上,或 container* 不在 Field box 上,则失败。证据缺口:没有测试断言调用方的 onFocus 会在进入处理之后运行。 |
audit:RadioList/api |
当前状态影响¶
- 组禁用原因(FR5)。 组的
disabledMessage仅描述 radiogroup,因此聚焦的禁用单选按钮不会由它描述,这有悖于spec:AST-085FR5 和 FR7。 - 禁用状态下调用方的 onClick(FR5)。 因组原因而保持可聚焦的 radio,在点击或方向键移动到它上面时仍会运行调用方的
onClick,这有悖于spec:AST-085FR2。 - 禁用聚焦性(FR5)。 未带原因禁用的组会为其单选按钮设置原生
disabled,使它们离开 Tab 顺序,这有悖于spec:AST-085FR1 和 FR7。 - 消费者文档。
RadioList.doc.mjs的结构(anatomy)部分列出了 Header、Children 和 Label/Value 部件;而 RadioList 渲染的是组标签、选项和状态消息,并且没有 header。
决策日志¶
- 键盘模型(FR4)。 RadioList 保留浏览器原生的 radio 方向键及其随附的 Tab 进入规则;
spec:AST-085将复合组件方向键访问哪些 radio 的事项交由复合组件自身决定。
RadioList 在其他方面应用 family:input-fields FR10 和 WAI-ARIA radio group 模式。
未决问题¶
无。
内容边界¶
本文件不重复消费者 prop 表格与示例、当前审计结果、实现步骤或家族/系统规则,而是链接到各自的维护方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx