跳转至

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-fields FR10 和 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-085 FR5 和 FR7。
  • 禁用状态下调用方的 onClick(FR5)。 因组原因而保持可聚焦的 radio,在点击或方向键移动到它上面时仍会运行调用方的 onClick,这有悖于 spec:AST-085 FR2。
  • 禁用聚焦性(FR5)。 未带原因禁用的组会为其单选按钮设置原生 disabled,使它们离开 Tab 顺序,这有悖于 spec:AST-085 FR1 和 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