跳转至

DropdownMenuRadioGroup 组件契约

契约一览

领域 契约
公共契约 一个受控、具名的单选组,包含 DropdownMenuRadioItem 子项,带有 value、变更回调、关闭策略、根输入和 ref。
行为 该组提供选择和关闭策略上下文;单选子项发出值;父级 DropdownMenu 负责键盘导航和菜单生命周期。
最终用户影响 当某个值匹配时,辅助技术会看到一个具名的组,且恰好有一个当前选项;同时指针和键盘选择保持一致。
构建者影响 保持 value 受控,提供稳定的可访问标签,并且组内只放置 DropdownMenuRadioItem 选项。
兼容性/就绪状态 记录已发布的行为;没有 API、默认值或 DOM 变更。
审查检查 拒绝未命名的组、本地选择状态、丢失的根输入、第二个键盘所有者,或绕过受控回调的关闭策略。
治理规则 spec:AST-020;architecture:public-component-api/INV5–INV9;architecture:component-test-sufficiency/INV1–INV7;spec:AST-020/FR1,FR2,FR6。

此表是审查预览;以下正文具有权威性。

意图

DropdownMenuRadioGroup 在 DropdownMenu 的指针呈现中渲染一个具名的 role="group" 包装器。它拥有受控选择上下文、关闭策略、根组合,以及子项之间基于 token 的间距。DropdownMenuRadioItem 拥有每个 menuitemradio 行及其选中状态;DropdownMenu 拥有焦点移动、typeahead、键盘激活、呈现以及菜单打开/关闭生命周期。

兼容性与迁移

  • 已发布的默认值保持不变:是(hasCloseOnSelect=true)。
  • 兼容性类别:记录已发布行为;没有公共 prop、默认值、导出或 DOM 变更。
  • 受控行为:value 归调用方所有,onChange 是唯一的提交路径。
  • 迁移决策:无。

消费者迁移说明应放在消费者文档和发布说明中。

所有权边界

拥有

  • 一个 role="group" 根节点,带有来自必填 label prop 的 aria-label。
  • 供单选子项使用的受控 value、onChange 和 hasCloseOnSelect 上下文。
  • 组根节点上 children、受支持的宿主输入、ref、className、style 和 xstyle 的组合。
  • 列布局和语义菜单的项间间距。

不拥有 / 非目标

  • menuitemradio 角色、aria-checked、禁用行为、指示器绘制、标签、描述、图标或尾部内容——由 DropdownMenuRadioItem 拥有。
  • 焦点进入、方向键导航、typeahead、Enter/Space 合成,以及菜单关闭实现——由 DropdownMenu 和共享菜单 hooks 拥有。
  • 触摸和 bottom-sheet 可选行渲染——由父级呈现拥有。
  • 非受控选择状态或子值注册。

公共概念

概念 封闭取值或状态 含义 默认值 拥有者 稳定性 无效值行为
选择 匹配的值;不匹配的值 控制哪个子项报告选中。 无 调用方和单选子项 稳定 没有匹配项时,所有子项都保持未选中。
提交 子项值 通过 onChange 发出选中的子项值。 必填 组上下文 稳定 组外的子项会导致该项拥有者抛出异常。
关闭策略 关闭;保持打开 控制某个子项在选择后是否请求 DropdownMenu 关闭。 关闭 组上下文和父级 稳定 省略时关闭。
可访问名称 必填 label;可选的 labelledby 为组命名;aria-labelledby 可指向可见文本。 label 组根节点 稳定 公共类型仍然要求 label。
根表面 ref;DOM/data/ARIA;class/style/xstyle/events 在保持组根节点的角色和名称的同时扩展它。 省略 公共组件 API 稳定 接受的输入会组合;拥有的 role 和 label 优先。

行为与布局契约

ID 不变量 依据
FR1 根节点暴露 role="group" 和非空的可访问名称。必填的 label 提供 aria-label;调用方的 aria-labelledby 可引用可见文本。 spec:AST-020;当前源码和测试
FR2 该组是受控的。它将每个单选子项的 value 与调用方的 value 比较,并且仅通过调用方的 onChange 发出选中的子项值;组外的单选子项会导致该项拥有者抛出异常。 当前公共 API 和测试
FR3 hasCloseOnSelect 默认为 true。当为 false 时,选择会通过 onChange 更新,同时父级菜单保持打开。 当前行为与测试
FR4 DropdownMenu 是唯一的键盘所有者。该组不添加 Tab 停靠点、按键处理器、键入查找或点击合成;它仅为子行提供上下文。 architecture:interaction-modality;父级测试
FR5 Ref、受支持的宿主属性与处理器、className、style 和 xstyle 会到达或组合在组根元素上,且不会替换其拥有的 role 或 aria-label。 architecture:public-component-api INV5–INV9;当前测试
FR6 该包装器是一个逻辑列,其令牌化间距与周围菜单的项目节奏一致;它不添加任何组件特定的方向性绘制或导航。 当前源码

允许的变化

  • AV1 — 子项。 DropdownMenuRadioItem 子项的数量、标签、描述、图标和支持内容可以变化。
  • AV2 — 选择。 任何字符串值(包括无匹配值)都可由调用方控制,而无需添加本地组状态。
  • AV3 — 根样式。 调用方的样式输入可以扩展包装器,同时 role、可访问标签、列流向和子项语义保持不变。

代表性状态

状态 必需不变量 允许的变化
匹配值 恰好匹配的子项报告 aria-checked=true。 子项内容和菜单尺寸。
无匹配值 每个子项都报告 aria-checked=false。 为空或不匹配的调用方值。
默认关闭 选择会发出该值并通过父级关闭。 指针操作或合成键盘操作。
保持打开 选择会发出该值、更新受控状态并保持菜单打开。 结果副本和选中的子项。
RTL / 窄屏 列顺序和令牌化间距保持不变,且无水平溢出。 父级菜单位置。

转换与优先级顺序

  • ORD1 — 选择。 子项激活 → 项所有者中的禁用保护 → 组 onChange(value) → 可选的父级关闭。
  • ORD2 — 根组合。 基础列/间距 → 调用方 xstyle;受支持的宿主输入与 class/style 进行组合,同时拥有的 role 和标签保持不变。

性能与资源

  • PR1 — 仅上下文。 该组会记忆化一个小的上下文值,且不拥有任何 Effect、监听器、观察器、定时器、请求、DOM 读取或资源生命周期。

可访问性契约

  • AR1 — 命名组。 该包装器是父级菜单内的一个命名 group。
  • AR2 — 单选行。 子项拥有 menuitemradio 和 aria-checked;该组不添加嵌套的原生输入,也不重复行语义。
  • AR3 — 键盘所有权。 DropdownMenu 拥有焦点收集和激活;该组本身从不进入 Tab 或方向键序列。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
组包装器 具有菜单语义性项间间距的逻辑列。 当前源码与间距令牌 结构性 FR1, FR5, FR6
选中的子项 一个子项通过 aria-checked 反映调用方的值。 DropdownMenuRadioItem 显著 FR2, AR2
方向/窄屏 子项顺序和间距保持不变,且不依赖物理方向假设。 双向性与父级布局 结构性 FR6

未记录任何组件本地的视觉决策。

家族与系统关系

  • architecture:public-component-api 负责根输入组合和已发布兼容性。
  • architecture:component-test-sufficiency 负责相应的可观察证据。
  • architecture:interaction-modality 和 DropdownMenu 负责键盘行为。
  • spec:AST-020 提供 WCAG/APG 采纳和证据层边界。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, AR1 DropdownMenuSelectable.test.tsx "在没有值匹配时命名并组合组根" 标签和调用方 aria-labelledby 缺少组 role、aria-label 或调用方 aria-labelledby 时判定为失败。 audit:DropdownMenuRadioGroup/semantics
FR2 DropdownMenuSelectable.test.tsx "使用所选值调用 onChange"、"在没有值匹配时命名并组合组根"(未选中任何项目),以及 "当 radio 项目在组外使用时抛出异常" 匹配值与不匹配值;组外的项目 选错行、跳过 onChange 的选择,或在组外仍可正常工作的项目,均判定为失败。 audit:DropdownMenuRadioGroup/behavior
FR3 DropdownMenuSelectable.test.tsx "在请求受控选择更新时保持菜单打开" hasCloseOnSelect={false} 尽管选择退出仍发生关闭则判定为失败。证据缺口:此处没有测试断言选择后的默认关闭。 audit:DropdownMenuRadioGroup/behavior
FR4, AR2, AR3 DropdownMenu.test.tsx "箭头导航可到达消费者渲染的 menuitemradio 和 menuitemcheckbox 项目" 以及 "使用 Enter 激活聚焦的 menuitemradio,使用 Space 激活 menuitemcheckbox" 箭头键与在 radio 行上按 Enter 箭头跳过的 radio 行或 Enter 无法激活的行,判定为失败。证据缺口:没有测试断言该组不添加 Tab 停留点或按键处理器。 audit:DropdownMenuRadioGroup/accessibility
FR5 DropdownMenuSelectable.test.tsx "在没有值匹配时命名并组合组根" Ref、宿主属性、class、style、处理器 丢失 ref、属性、class、style 或处理器,或 role 或标签被替换,判定为失败。证据缺口:没有测试断言组上的 xstyle。 audit:DropdownMenuRadioGroup/api
FR6, PR1 apps/storybook/rtl-audit/verified-not-applicable.json 中的 DropdownMenuRadioGroup 条目。证据缺口:没有测试断言列间距或不存在生命周期资源。 LTR 和 RTL 源哈希一旦更改,收据校验即失败。 audit:DropdownMenuRadioGroup/layout

决策日志

无组件级本地决策。

未决问题

无。

内容边界

本文件不重复使用方属性表/示例、当前审计分数、截图矩阵、实现步骤或父级/子级契约。它会链接到这些内容的所属方。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx