DropdownMenuSubMenu 组件契约¶
契约概览¶
| 方面 | 契约 |
|---|---|
| 公共契约 | 一行 menuitem:标签、子项;可选图标、描述、加载展开箭头、禁用状态、浮出层宽度、呈现方式、delay、hideDelay、头部、底部、打开回调、测试 ID、根输入、一个 ref。 |
| 行为 | 该行将其子项显示为旁边的浮出层,或显示为带返回行的下钻视图;若带有头部或底部,该表面就是一个以该行命名的模态对话框。 |
| 最终用户影响 | 指针、键盘和触控用户可从一行到达嵌套命令;辅助技术会听到该行的弹出类型和展开状态,按 Escape 或点击关闭箭头可返回该行。 |
| 构建者影响 | 将该行放在 DropdownMenu 或 ContextMenu 中,并为其提供标签和行;数据驱动的菜单从嵌套的 items 数组获取它。 |
| 兼容性与就绪状态 | 记录已发布行为;在发布时机新增可选的 delay 和 hideDelay(FR11);禁用行获得 tabindex="-1"(FR7)。 |
| 审查检查 | 拒绝第二个键盘所有者、丢失的弹出状态、在 RTL 下不翻转的浮出层、可打开的禁用行、丢失的调用方输入,或错过过渡的打开回调。 |
| 治理规则 | spec:AST-020 FR15;architecture:public-component-api/INV5–INV8;architecture:react-component-runtime/INV2;architecture:layer-runtime;spec:AST-020/FR1,FR2;spec:AST-086/FR8。 |
此表是审查投影;下文为权威内容。
意图¶
DropdownMenuSubMenu 将一行菜单变为嵌套菜单的入口点。
该行拥有其 menuitem 语义、弹出状态、展开箭头或加载指示器、禁用绘制,以及其子项渲染所在的表面:由 layer runtime 定位在该行旁边的浮出层,或根菜单代替自身行所显示的视图。每一层拥有自己的漫游焦点、键入查找和按压模型。
DropdownMenu 拥有根表面、下钻视图栈,以及带有头部或底部的子菜单所渲染到的表面宿主。
兼容性与迁移¶
- 已发布的默认值保留:是(
isDisabled=false、hasSpinner=false、presentation='adaptive'、delay=150、hideDelay=200)。 - 兼容性类别:增量式;该行新增可选的
delay和hideDelay(FR11),其默认值为已发布的时序;禁用行获得tabindex="-1"(FR7)。 - 受控行为:打开状态是内部的;
onOpenChange报告该状态。 - 迁移决策:无。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 一行根元素,带有
role="menuitem"、aria-haspopup(menu,或带头部或底部的dialog)、aria-expanded,以及打开时的aria-controls。 - 浮出层菜单、其视口限制的大小、其键盘处理及其悬停意图;下钻列表及其返回行。
- 头部和底部区域,以及承载它们的模态对话框。
- ref、受支持的宿主输入、
className、style、xstyle以及组合后的onClick、onKeyDown、onPointerMove、onMouseEnter和onMouseLeave处理器的根组合。
不拥有 / 非目标
- 根菜单表面、下钻视图栈及其在菜单关闭时的重置,以及表面宿主——由
component:DropdownMenu拥有。 - 叶子行行为——由
component:DropdownMenuItem和可选项契约拥有。 - 定位、翻转和视口内边距——由
architecture:layer-runtime拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 变体/方向/状态下的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 呈现方式 | flyout; drill-in; adaptive | 子项渲染的位置;当用手指打开菜单时,adaptive 会下钻。 | 每一行;drill-in 需要菜单根 | adaptive | component:DropdownMenuSubMenu |
稳定 | 未知值会被公共类型拒绝。 |
| 可用性 | enabled; disabled | 该行能否打开。 | 每一行 | enabled | component:DropdownMenuSubMenu |
稳定 | 禁用行永远不会打开。 |
| 加载状态 | caret; spinner | 该行的子项加载时,其末端是否显示加载指示器。 | 每一行 | caret | component:DropdownMenuSubMenu |
稳定 | 该行仍会打开;空浮出层会自行获得焦点。 |
| 区域 | none; header; footer; both | 子菜单菜单旁边的内容,将其表面变成对话框。 | 在 DropdownMenu 根内 | none | component:DropdownMenuSubMenu |
稳定 | 没有表面宿主时,这些区域不会渲染。 |
| 打开报告 | open; close | onOpenChange 报告该行浮层的每次状态转换。 |
每一行 | 省略 | component:DropdownMenuSubMenu |
稳定 | 已记录的缺口见 FR6。 |
| 根浮层 | ref; DOM/data/ARIA; class/style/xstyle; handlers | 扩展该行的根节点,同时保留其角色(role)和弹出式接线(popup wiring)。 | 每一行 | 省略 | public component API | 稳定 | role 和 tabIndex 不被接受。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 该行暴露 role="menuitem"、aria-haspopup="menu"(有 header 或 footer 时为 "dialog")、与其浮层状态匹配的 aria-expanded,以及在打开时指向该浮层的 aria-controls。该浮层由该行提供标签。 |
spec:AST-020;当前源码和测试 |
| FR2 | 单击、Enter、Space 或 inline-end 箭头(RTL 下为 inline-start 箭头)会打开浮层;通过键盘打开时,焦点会移到其第一个启用的行上。Escape 或关闭箭头只关闭当前层级,并将焦点返回到该行。悬停会在意图延迟(intent delay)后打开 flyout。 | spec:AST-020;architecture:interaction-modality;当前测试 |
| FR3 | flyout 位于该行的 inline-end 一侧,随方向翻转,并保持在视口内;其 block size 上限取自身上限与视口上限中的较小值。 | architecture:layer-runtime;当前源码 |
| FR4 | 下钻视图(drilled-in view)会用一行以父菜单命名的 Back 行,后接该行的子项,来替换根菜单中的行;Back、Escape 和关闭箭头都会返回到该行。 | 当前源码和针对性测试 |
| FR5 | 在该浮层内选择叶子行会关闭所有层级以及根菜单。 | 当前源码和测试 |
| FR6 | onOpenChange MUST 在浮层打开时报告一次 true,并在浮层关闭时报告一次 false;该报告应来自导致该变化的动作。实现缺口:由根菜单关闭而重置的下钻视图不会报告 false(OQ1)。 |
文档化承诺;architecture:react-component-runtime INV2 |
| FR7 | 禁用行暴露 aria-disabled="true",带有 tabindex="-1",以便父级的键盘模型能到达它(component:DropdownMenu FR17);它不因悬停获得焦点,不因任何输入而打开,也不会执行调用方的 onClick。 |
当前源码和测试 |
| FR8 | 在 hasSpinner 为 true 时,该行会以装饰性 spinner 代替 caret,并在根菜单显示后播报忙碌(busy)状态的开始。 |
spec:AST-086 FR8;当前源码和测试 |
| FR9 | Ref、受支持的宿主属性和 handlers、className、style 与 xstyle 会在该行自身行为之后到达或组合到该行根节点;打开键和禁用态点击会在调用方 handler 之前被拦截。 |
architecture:public-component-api INV5–INV8;当前测试 |
| FR10 | 如果该行没有自己的 header 或 footer,且其上方层级也没有,则 flyout 中某行上的 Tab 或 Shift+Tab 会在按键冒泡到菜单时关闭当前层级,从而关闭整个菜单(component:DropdownMenu FR23、component:ContextMenu FR11)。 |
WAI-ARIA Menu Button 模式;当前测试 |
| FR11 | 在支持悬停的指针上,flyout 会在 delay 毫秒后打开,并在指针离开该行、flyout 以及通往它的路径(component:DropdownMenu FR13)后,经过 hideDelay 毫秒关闭(默认分别为 150 和 200)。键盘焦点和触摸从不等待这些延迟。 |
负责人决策,2026-11-06 |
允许的变体¶
- AV1 — 内容(Content)。 标签(label)、图标、描述和子项可变;长字符串标签在一行内截断。
- AV2 — 尺寸(Size)。 该行的内边距(padding)跟随父级菜单尺寸。
- AV3 — 宽度(Width)。
menuWidth在视口上限内设置 flyout 的最小宽度。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 已关闭 | aria-expanded=false;行末显示箭头指示符或加载指示器。 |
内容、尺寸、主题和模式。 |
| 已打开 | aria-expanded=true;浮层位于行旁,并以该行为标签。 |
通过指针、键盘或按压打开。 |
| 已下钻 | 先显示返回行,然后在根容器中显示子项。 | 嵌套下钻深度。 |
| 区域 | 由该行命名的模态对话框;Tab 依次经过头部、行、底部,并循环。 | 仅头部或仅底部。 |
| 已禁用 | aria-disabled=true,无 Tab 停靠点,半透明,不可打开。 |
是否处于加载状态。 |
| RTL | 箭头指示符镜像一次;浮层朝行内末端方向打开。 | 在视口边缘处翻转放置。 |
状态转换与优先级顺序¶
- ORD1 — 点击。 禁用保护 → 下钻推入或浮层切换 → 调用方
onClick。 - ORD2 — 按键。 打开键被处理并阻止传播 → 其他任何按键交给调用方的
onKeyDown。 - ORD3 — 叶节点选择。 叶节点操作 → 本级关闭 → 父级关闭 → 根菜单关闭。
性能与资源¶
- PR1 — 自有资源。 该行仅有的定时器是悬停意图检测器和失焦时的零延迟焦点检查;浮层的溢出观察遵循共享菜单溢出钩子。
无障碍契约¶
- AR1 — 单一入口行。 该行是一个菜单项,其弹出类型和状态通过 ARIA 暴露;其箭头指示符和加载指示器是装饰性的。
- AR2 — 层级作用域按键。 每一层拥有自己的方向键、键入搜索和 Escape;更深层级的按键绝不会作用于其父级。
- AR3 — 禁用项的可发现性。 键盘可到达禁用行,如
component:DropdownMenuFR17 所述。 - AR4 — 焦点可见性。 键盘焦点在行内绘制共享焦点环,并按焦点环自身宽度内缩;这适用于所有颜色模式,包括强制颜色。指针输入后,该行仅显示覆盖色调(
architecture:interaction-modalityINV1、INV3)。共享行样式为component:DropdownMenuItemFR8。
设计关系¶
| 结构或状态 | 设计要求 | 呈现负责方 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 行 | 菜单行的绘制、圆角和尺寸内边距;焦点绘制见 AR4。 | 当前源和菜单令牌 | 结构性 | FR1、AR4 |
| 箭头指示符 / 加载指示器 | 镜像的箭头指示符,或加载时的装饰性加载指示器。 | 图标和加载指示器负责人 | 辅助性 | FR3、FR8 |
| 浮层 | 弹出表面、低阴影、容器圆角、视口约束。 | 当前源和图层运行时 | 突显性 | FR3 |
| 下钻视图 | 行位于根容器内,由镜像的返回行引领。 | 当前源 | 结构性 | FR4 |
| 已禁用 | 半透明行,默认光标。 | 当前源 | 辅助性 | FR7 |
此处不记录任何组件局部的视觉决策。
家族与系统关系¶
component:DropdownMenu拥有根表面、下钻栈、表面宿主、dropdown-menu、dropdown-menu-item和dropdown-menu-indicator-icon目标清单,以及禁用行的键盘可达性(其 FR17)。architecture:layer-runtime负责浮层的放置、翻转和内边距。architecture:public-component-api负责根输入与处理程序的组合。architecture:react-component-runtime负责回调时机。spec:AST-086负责加载播报。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1、AR1 | DropdownMenuSubMenu.test.tsx“使用 aria-haspopup 和折叠的 aria-expanded 渲染触发器”、“通过 aria-labelledby 以触发器为浮层命名”、“该行保持自身的弹出状态和 Tab 停靠点”;头部-底部情形“将头部、行和底部保存在由该行命名的对话框中,且位于所有菜单之外” |
已关闭和已打开;带区域 | 缺少 aria-haspopup、aria-expanded,或表面缺少行标签时失败。证据缺口:没有测试在打开状态下断言 aria-controls。 |
audit:DropdownMenuSubMenu/semantics |
| FR2, AR2 | DropdownMenuSubMenu.test.tsx “在触发器点击时打开浮层并展示其项目”、“按下 ArrowRight 时打开,并在按下 ArrowLeft 时将焦点返回触发器”、“在 RTL 下镜像其指示器和键盘方向”、“按下 Escape 时仅关闭子菜单并将焦点恢复到触发器”、“支持浮层内的首字符提前输入”、“导航两级嵌套子菜单时不发生双重步进”、“在悬停时将焦点移至子菜单触发器,保持单一高亮”;悬停/点击防护用例 |
点击、方向键、RTL、Escape、悬停、嵌套 | 无法打开或关闭的按键、错误的焦点目标、双重步进的层级,或反向的 RTL 箭头均失败。证据缺口:没有测试断言 Enter 或 Space 会打开该行。 | audit:DropdownMenuSubMenu/accessibility |
| FR3 | DropdownMenuSubMenu.test.tsx “将浮层宽度和高度限制为可用视口”;apps/storybook/rtl-audit/targets.json 中的 DropdownMenuSubMenu 条目 |
视口限制;RTL | 超出视口的浮层失败。证据缺口:没有测试断言 inline-end 放置或其翻转。 | audit:DropdownMenuSubMenu/layout |
| FR4 | DropdownMenuSubMenu.test.tsx 的钻入用例;DropdownMenuDrillIn.a11y.chromium.spec.ts |
钻入视图;Back | 缺少 Back 行,或 Back 无法返回时失败。 | audit:DropdownMenuSubMenu/behavior |
| FR5 | DropdownMenuSubMenu.test.tsx “选择嵌套项目后关闭整个菜单”以及“使用 Enter 键激活嵌套项目并关闭菜单” |
指针和 Enter | 选择叶节点后仍保持打开的层级失败。 | audit:DropdownMenuSubMenu/behavior |
| FR6 | DropdownMenuSubMenu.test.tsx “向 onOpenChange 报告每次浮层打开和关闭一次” |
浮层打开和关闭 | 缺失或重复的报告失败。证据缺口:未断言钻入重置间隙。 | audit:DropdownMenuSubMenu/behavior |
| FR10 | DropdownMenuSubMenu.test.tsx 中“按 Tab 从浮出菜单移出并离开整个菜单”测试套件;ContextMenu.test.tsx 中的对应用例 |
一级和两级菜单,Shift+Tab | 若 Tab 后仍有浮出菜单保持打开,则失败。 | audit:DropdownMenuSubMenu/accessibility |
| FR11 | DropdownMenuSubMenu.test.tsx 中“默认在悬停 150 毫秒后打开,并在指针离开 200 毫秒后关闭”、“在悬停打开浮出菜单前等待给定的 delay 时间”以及“在指针离开后将浮出菜单保持打开给定的 hideDelay 时间” |
delay;hideDelay;默认值 |
若浮出菜单在 delay 之前打开或在 hideDelay 之前关闭,则失败。 |
audit:DropdownMenuSubMenu/behavior |
| FR7, FR9 | DropdownMenuSubMenu.test.tsx 中“不打开已禁用的子菜单”、“禁用行不会将点击传给调用方的 onClick”、宿主属性和 ref 用例(“aria-*、data-* 和 id 会到达触发行,且浮出菜单仍由其提供标签”、“ref 会到达触发行”、“调用方的处理器在行自身的处理器之后运行,且行仍会打开并获得悬停焦点”) |
禁用;调用方处理器和属性 | 禁用项被打开、调用方点击被触发,或属性、ref 或处理器丢失,均失败。证据缺口:没有测试断言行上的 className、style 或 xstyle、禁用行的 tabindex="-1",或父级键盘能否到达该行(component:DropdownMenu FR17)。 |
audit:DropdownMenuSubMenu/api |
| FR8 | BusyOwnerAnnouncement.test.tsx 的“DropdownMenuSubMenu 加载状态”用例;DropdownMenuSubMenu.test.tsx 的加载浮出菜单用例 |
加载时的关闭和打开状态 | 在关闭状态下宣布忙碌开始、宣布两次、完全不宣布,或宣布了 Spinner,均失败。 | audit:DropdownMenuSubMenu/accessibility |
| AR4, PR1 | DropdownMenuForcedColors.test.tsx(行的 :focus-visible 焦点环和 token 内边距);DropdownMenuAudit.a11y.chromium.spec.ts 的 forced-colors 帧。证据缺口:没有测试断言定时器边界 |
— | — | audit:DropdownMenuSubMenu/visual |
当前状态影响¶
- 下钻关闭报告 (FR6)。 当根菜单关闭一个下钻视图时,
onOpenChange(false)不会执行 (OQ1)。
决策日志¶
无组件本地决策。
未决问题¶
- OQ1 — 当根菜单关闭时,由哪个所有者报告下钻视图的关闭? (
human-api) 浮出层通过其层报告每次关闭,但根会重置下钻栈而不通知该行,因此对于那次关闭onOpenChange(false)永远不会执行。该栈由component:DropdownMenu持有。
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计评分、截图矩阵、实施步骤或根/叶契约。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx