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"根节点,带有来自必填labelprop 的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