跳转至

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:DropdownMenu FR17 所述。
  • AR4 — 焦点可见性。 键盘焦点在行内绘制共享焦点环,并按焦点环自身宽度内缩;这适用于所有颜色模式,包括强制颜色。指针输入后,该行仅显示覆盖色调(architecture:interaction-modality INV1、INV3)。共享行样式为 component:DropdownMenuItem FR8。

设计关系

结构或状态 设计要求 呈现负责方 层级角色 组件契约
行 菜单行的绘制、圆角和尺寸内边距;焦点绘制见 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