跳转至

useMenuHover 模块契约

契约概览

区域 契约
公共契约 无。useMenuHover 是一个内部共享 hook;DropdownMenu、SideNav 或 TopNav 的消费者 prop、导出或 DOM 契约均无变化。本记录将已经发布的行为契约化。
行为 具备悬停能力的指针进入触发器会在 showDelay 后打开,离开则会在 hideDelay 后关闭由悬停打开的面板。指针在触发器上的按下会切换(TOGGLE),但在悬停打开后的 clickGuardMs 窗口内除外,此时会改为确认面板。由按下打开的面板没有此类窗口。
最终用户影响 当用户的鼠标光标移向某一行,并在浮层在其下方出现时点击,该浮层会保留;同一用户片刻后按下那个明显已打开的行则会将其关闭。键盘或触摸用户不受影响:两条路径都没有悬停阶段,也都没有切换行为。
构建者影响 无。clickGuardMs: 0 使面板选择退出,因此每次按下都会切换(SideNavItem 即如此);showDelay: 0 在接触时立即打开;ownsFocus: false 将焦点留给面板自身的焦点陷阱。
兼容性/就绪状态 无行为、API 或默认值变化。权威状态:draft——cixzhang 于 2026-10-02 确定了按下切换规则及其守卫例外(DEC-1),并在其 pull request 上批准本记录。jsdom 覆盖延迟、守卫、焦点和 invoker 属性;原生轻触关闭仅限浏览器。
审查检查项 拒绝无法关闭用户可以看到处于打开状态的面板的按下;拒绝由按下打开所武装的守卫;拒绝通过重新进入已打开的触发器而重新武装的守卫;拒绝将悬停作为到达面板的唯一方式;拒绝移动焦点的悬停打开;拒绝在第二次激活时关闭的键盘路径。
约束规则 architecture:interaction-modality INV2–INV4(模态性与焦点所有权保持分离;一次焦点移动只有一个指示器;每种模态都有可操作的路径,悬停绝不是唯一路径);architecture:layer-runtime 负责原生 invoker 关系和合成 mouseenter 的说明。

此表为审查概览;下方正文具有权威性。

意图

在桌面指针环境下,浮层菜单应当跟随光标:面板因悬停意图而打开,而非要求按下;当指针移向他处时关闭。useMenuHover 是决定这一行为的唯一位置,因此子菜单和导航浮层无需各自发明自己的延迟、自己的守卫,也无需各自回答“按下会关闭它吗?”这个问题。

该行为已经发布并持续了一段时间;它缺少的只是一份记录。正因为没有任何说明表明这部分很重要,一个删除其中一部分的公开提案才是合理的。本记录为每个挂载该 hook 的面板契约化悬停意图模型——打开、关闭、按下切换和点击守卫。

它只契约化悬停模型。打开菜单内部的按下模型、菜单结构、项语义、方向性键盘导航和图层关闭仍归各自的所有者负责。

兼容性与迁移

  • 已发布的默认值保持不变:yes——本记录描述当前 main 分支,并且不改变任何运行时行为、默认值或签名
  • 兼容性类别:对已发布行为的文档化;无 API、默认值或可观察差异
  • 迁移决策:无需迁移

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 触发器上的悬停意图:悬停打开面板之前的延迟,以及离开触发器或面板后关闭由悬停打开的面板之前的延迟。
  • 指针在触发器上的按下是打开、确认还是关闭——包括点击守卫及其运行的窗口。
  • 抑制关闭中的面板在停止覆盖静止指针时触发的合成 mouseenter 事件。
  • 在无法悬停的指针上完全退出。
  • 该 hook 执行打开时焦点应该去向何处,以及在 hook 自身关闭时将焦点返回到触发器。
  • 位于自动 popover 外部的触发器的原生 invoker 关系(popovertarget),以及取消该 invoker 的默认切换,以便由一个 handler 决定。

不拥有 / 非目标

  • 聚合菜单结构、呈现解析、项渲染和主题化——由 component:DropdownMenu 和所属导航组件拥有。
  • 按下对打开菜单内部某行的作用——由 module:DropdownMenu/useMenuPress 拥有。
  • 方向性打开和关闭按键(ArrowRight / ArrowLeft,以及它们的 RTL 镜像)——由渲染触发器的组件拥有。该 hook 只看到 Enter 和 Space,且仅因为浏览器将它们作为 click 传递。
  • 面板内部的 Typeahead 和漫游导航——由 useListFocus 和 useTypeahead 拥有。
  • 原生轻触关闭、跨图层的 Escape 顺序和焦点陷阱——由 architecture:layer-runtime 和 family:overlay-dismissal 拥有。
  • 定位、锚定和碰撞行为——由 useLayer 拥有。
  • 对于给定触发器,面板是否完全存在:传入 isEnabled: false 的消费者将获得无操作的 handlers,且没有任何悬停行为。

公共 API 与概念

概念 封闭值或状态 含义 默认值 负责人 稳定性
打开来源 hover-opened、pinned 当前打开是如何开始的;只有 hover-opened 面板会在指针离开时关闭,也只有它会启动点击保护 来自触发打开的事件 module:DropdownMenu/useMenuHover 稳定
showDelay 毫秒,0 表示接触即打开 打开前的悬停意图等待时间 150 module:DropdownMenu/useMenuHover 稳定
hideDelay 毫秒 离开触发器或面板后、hover-opened 面板关闭前的宽限期 200 module:DropdownMenu/useMenuHover 稳定
clickGuardMs 毫秒,0 表示退出 悬停打开后的时间窗;在此窗口内按下会确认面板而非关闭它 500 module:DropdownMenu/useMenuHover 稳定
重新打开抑制 任何关闭后的固定时间窗 因面板不再遮挡静止指针而到达的 mouseenter 会被忽略;真正的指针离开会提前清除该状态 300 毫秒,不可配置 module:DropdownMenu/useMenuHover 稳定
悬停能力 匹配 (hover: hover),或不匹配 是否读取悬停意图;粗指针不会安排任何打开 来自媒体查询 architecture:interaction-modality 稳定
ownsFocus true、false 该 hook 在按下或键盘打开时是否移动焦点,还是将焦点交给面板自身的焦点陷阱 true module:DropdownMenu/useMenuHover 稳定
popoverId 弹层的 DOM id,或不存在 存在时使触发器成为面板的原生调用者,从而免于轻触关闭;hook 随后取消调用者自身的切换行为 不存在 architecture:layer-runtime 稳定
集成形态 完整,或仅指针 使用方要么采用完整模型,要么只采用悬停意图和 confirmHoverOpen,并保留自己的按下与键盘处理 完整 module:DropdownMenu/useMenuHover 稳定

行为契约

ID 候选不变式 依据 草稿审查状态
FR1 具备悬停能力的指针进入已启用的触发器时,MUST 在 showDelay 之后打开面板,并且 MUST NOT 移动焦点:此时由指针驱动。showDelay: 0 表示接触即打开。 当前行为;useMenuHover.test.tsx、SideNav.test.tsx 已定稿
FR2 离开触发器或面板时,MUST 在 hideDelay 之后关闭 hover-opened 面板;进入面板时 MUST 取消待执行的关闭。pinned 面板 MUST NOT 在指针离开时关闭。 当前行为;useMenuHover.test.tsx、SideNav.test.tsx 已定稿
FR3 在触发器上按下指针 MUST 切换面板:打开已关闭的面板,并关闭已打开的面板。这是默认答案,FR4 是唯一例外。 DEC-1;useMenuHover.test.tsx、DropdownMenuSubMenu.test.tsx 已定稿
FR4 在悬停打开后的 clickGuardMs 时间窗内落下的按下操作 MUST 确认该面板而非关闭它,将其固定(FR2),并在 hook 拥有焦点时将焦点移入。窗口期过后,按下 MUST 关闭它。clickGuardMs: 0 表示退出,使每次按下都切换。 DEC-1;useMenuHover.test.tsx、DropdownMenuSubMenu.test.tsx 已定稿
FR5 保护机制 MUST 以悬停打开为准,绝不以打开为准。因此,通过按下打开的面板完全没有时间窗,下一次按下会立即关闭它。这是该规则的预期结果,而非边界情况。 DEC-1;useMenuHover.test.tsx 中的仅点击和重新进入用例 已定稿
FR6 重新进入已打开面板的触发器时,MUST NOT 重新激活保护机制,也 MUST NOT 使面板再次变为 hover-opened;否则下一次有意按下将永远确认该面板,且该面板永远无法通过指针关闭。 当前行为;useMenuHover.test.tsx 中的重新进入用例 已定稿
FR7 在任意关闭后的固定时间窗口内,触发器上的 mouseenter MUST NOT 重新打开浮层,因为定位在自身触发器上方的面板会让触发器重新处于静止指针之下。真实的指针离开事件 MUST 提前清除该窗口,以便有意的重新悬停仍能打开。 当前行为;useMenuHover.test.tsx 的抑制与重新悬停用例 已确定
FR8 当 (hover: hover) 不匹配时,mouseenter 和 mouseleave MUST 不调度任何操作——一次点按产生的兼容性 mouseenter 不得让浮层在背后悬空打开——且按压路径 MUST 与支持悬停的指针下的行为完全一致。 architecture:interaction-modality INV4;useMenuHover.test.tsx、SideNav.test.tsx 已确定
FR9 键盘激活触发器 MUST 始终打开浮层并将焦点移入其中,并且 MUST 绝不关闭它。键盘没有切换功能;FR3 的切换是一种指针可供性,键盘上没有按键镜像这一行为。 当前行为;useMenuHover.test.tsx 键盘测试套件 已确定
FR10 当焦点位于浮层内时,Escape MUST 关闭浮层并将焦点返回到触发器。方向性打开与关闭按键属于使用组件,而非此钩子。 family:overlay-dismissal;useMenuHover.test.tsx、DropdownMenuSubMenu.test.tsx 已确定
FR11 当提供了 popoverId 时,触发器 MUST 为该面板携带 popovertarget,并且钩子 MUST 取消由此产生的 invoker 切换,以便其自身的处理器成为 FR3 和 FR4 的唯一决策点。 architecture:layer-runtime;useMenuHover.test.tsx 的 invoker 用例 待验证
FR12 禁用的集成 MUST 不为其触发器添加任何悬停行为,并且 MUST NOT 打开浮层:在悬停进行中时触发器被禁用则保持关闭,无论禁用发生在指针到达之前,还是在本会打开它的延迟期间。 当前行为;SideNav.test.tsx 折叠/展开用例 待验证

转换与优先级顺序

  • ORD1 — 按压解析。 键盘激活(FR9)→ 浮层已关闭,则打开 → 在守卫窗口内,则确认(FR4)→ 否则关闭(FR3)。第一个匹配的分支决定执行;后续分支都不会运行。
  • ORD2 — 悬停进入解析。 没有支持悬停的指针,则不执行任何操作(FR8)→ 处于重新打开抑制窗口内,则不执行任何操作(FR7)→ 已打开,则放弃任何待执行的关闭并保持其他一切不变(FR6)→ 否则浮层在 showDelay 之后变为 hover-opened(FR1)。
  • ORD3 — 来源清除。 任何关闭,无论由什么引起,都会清除 hover-opened,并在浏览器对已消失的面板进行命中测试之前标记抑制窗口;一次确认操作会在不关闭的情况下清除 hover-opened。

性能与资源

  • PR1 — 待执行意图不会比取代它的意图更持久。 最多只会有一个打开和一个关闭处于待执行状态;较新的意图会替换待执行的意图,而不是在其后排队,并且当浮层卸载时,不会有任何待执行意图存活。被已移除浮层遗留下来的触发器无法打开该浮层。
  • PR2 — 在触发器及其浮层之外不观察任何内容。 悬停意图仅从触发器和浮层读取,因此包含许多触发器的页面不会为每个触发器承担文档级或窗口级开销。

无障碍契约

  • AR1 — 悬停打开从不移动焦点。 指针正在驱动,因此焦点停留在用户离开的位置;浮层可用打开它的同一指针触及。这使得模态性和焦点所有权保持分离(architecture:interaction-modality INV2)。
  • AR2 — 按压或键盘打开会同步将焦点移入。 在钩子拥有焦点的情况下,它会在同一 tick 中聚焦第一个启用项,当浮层为空或仍在加载时回退到浮层容器,因此键盘所有权始终脱离触发器的列表。如果消费者的浮层是焦点受限的对话框而非菜单,则传入 ownsFocus: false,由焦点陷阱拥有焦点。
  • AR3 — 关闭将焦点返回到触发器。 当焦点位于浮层内时,钩子自身的关闭操作会将焦点返回到触发器,因此 Escape 永远不会让键盘用户滞留在已消失的元素上。
  • AR4 — 悬停是一种增强,而非必需条件。 该钩子打开的每个浮层 MUST 保持可通过按压和键盘触及与关闭,且不涉及任何悬停阶段(architecture:interaction-modality INV4)。粗指针获得的按压路径不变(FR8)。
  • AR5 — 每次焦点移动只有一个高亮。 钩子将焦点精确地移动到一个项目上,且自身不绘制任何内容;在悬停时也进行高亮的浮层会将高亮和焦点保持在同一个位置(architecture:interaction-modality INV3)。

设计关系

解剖结构或状态 设计需求 表示权威 模块契约
打开的表面 不引入任何视觉表示;表面自身的外观属于所属组件 规定 FR1、FR3
聚焦条目 由条目组件拥有的现有焦点高亮;本模块仅决定哪一项获得它 规定 AR2、AR5

父级与系统关系

  • component:DropdownMenu 拥有聚合菜单结构、呈现解析和条目管线。本模块被置于其下,是因为仓库的知识路径规则要求模块记录位于具有活动组件记录的组件根之下并由其列出;在消费该 hook 的三个根(DropdownMenu、SideNav、TopNav)中,只有 DropdownMenu 拥有这样的记录,而同级按压模型也已基于相同理由被置于其下。该契约约束所有消费者,而不仅仅是子菜单。
  • module:DropdownMenu/useMenuPress 是同级按压模型,边界划分明确:它决定按压对打开菜单内部的某一行产生什么效果;本记录决定按压触发器对表面本身产生什么效果。两者互不支配对方的表面。
  • architecture:layer-runtime 拥有层的生命周期、原生轻触关闭,并且已记录该 hook 为适用的自动弹出层添加了真实的原生 invoker 关系,同时抑制关闭中的面板所产生的合成 mouseenter 事件。它还记录到,打开层旁边的控件在按压期间可能临时获得 popovertarget,并且其 invoker 切换可能被取消;FR11 是该关系在此 hook 中的典型实例,而非第二条规则。
  • architecture:interaction-modality 拥有模态状态以及 AR1、AR4 和 AR5 所投射的不变式;本记录不新增任何模态定义。
  • family:overlay-dismissal 拥有跨层的 Escape 顺序;此处不变。
  • SideNav 和 TopNav 目前还没有组件记录。当其中任一获得记录时,它应引用本模块,而不是重新陈述悬停模型。

验证映射

契约 验证 代表性状态 变更或失败预期
FR1–FR2、FR5–FR7、FR9、FR10 useMenuHover.test.tsx,通过真实消费者驱动,而非合成测试装置 悬停打开、离开关闭、立即按压、窗口期过后按压、仅按压切换、触发器重新进入、面板消失后进入 移除保护会使立即按压用例失败;将其扩大到按压即打开会使重新进入和仅点击用例失败
FR3–FR5 DropdownMenuSubMenu.test.tsx 悬停/点击保护套件 弹出层悬停打开后立即按压;弹出层悬停打开后超过窗口期再按压 永远无法关闭可见打开弹出层的按压会使第二个用例失败
FR1、FR2、FR8、FR12 SideNav.test.tsx 折叠子菜单悬停意图套件 精确指针与粗略指针、延迟边界、待打开期间卸载、clickGuardMs: 0 消费者 粗略指针对时间进行调度,或禁用项仍可悬停打开,则失败
FR9、AR1–AR3 useMenuHover.test.tsx 焦点与键盘套件 悬停打开保留焦点;按压打开在同一 tick 内聚焦第一个条目;在打开的表面上按 Enter;Escape 延迟(绘制后)焦点失败;关闭表面的键盘激活失败
FR11 useMenuHover.test.tsx 的 invoker 用例断言接线;该行为仅存在于浏览器中 自动弹出层之外的触发器 jsdom 既不实现轻触关闭,也不实现 invoker,因此断言该属性存在,而关闭行为无法被证明
AR4 上述每个套件中的按压与键盘路径 每个消费者,没有悬停可用 仅能通过悬停到达的表面会违反 architecture:interaction-modality 的 INV4

决策日志

DEC-1 — 按压切换,悬停打开后紧随的按压除外

参考: module:DropdownMenu/useMenuHover/DEC-1 决策者: cixzhang,2026-10-02

按下子菜单行会切换弹出层的开闭,但有一个例外:紧接在悬停打开之后落下的点击不会将其关闭。

悬停与点击是同一次连续动作,而不是两个独立决定。用户将光标移向该行,弹出层在移动途中于光标下方打开,而用户早已决定要执行的点击落在了一个刚刚出现的对象上。保护窗口识别到该点击原本是针对处于关闭状态的那一行,因此它确认该表面,而不是将其撤销。

窗口过后,情况就不同了:用户按下的是他们能看到已经打开的内容,而这是第二次有意的按下。它应当将其关闭——“等待片刻后再次点击菜单切换按钮应将其关闭”,并且“我们应该保留这一行为”。

这正是守卫以悬停打开状态、而非以打开状态为判定依据的原因(FR5):用户通过按下而打开的表面从来都不属于歧义情形,因此下一次按下会直接将其关闭,完全不需要窗口。某个消费者的表面不会出现在移动中的光标下方——即在侧栏旁打开、而不是在触发器上方打开的那种——它没有歧义需要解决,因此将 clickGuardMs 设为 0。

未决问题

  • OQ1 — 某个消费者自行处理按下规则。 (checkable) 六个消费者中有五个采用整个模型。DropdownMenuSubMenu 只采用悬停意图,并在自己的按下处理中解决 FR3 和 FR4,因此该规则存在于两处,两者可能发生分歧。负责人的方向是收敛:每个消费者都应从同一个地方获得 FR3 和 FR4。按下操作对同时作为菜单项的菜单行会产生什么影响,这才是尚未解决的部分,因为该行同样受 module:DropdownMenu/useMenuPress 管辖;无论哪种方式,两种形态都必须产生的那种行为都已确定。

  • OQ2 — 键盘激活无法可靠区分。 (checkable) FR9 要求键盘激活能够打开且永不关闭,这取决于能否将其与同一触发器上的指针激活区分开来。一个同时承载着会自行分派激活的模型的触发器,无法通过浏览器在按键时给出的信号来区分,因此 FR9 的保证在那里不成立。没有已发布的表面受到影响,因为同时承载两者的那一行保留了自己的按下处理(OQ1)——但收敛 OQ1 会使这种情况变得可达,因此两者应一并解决。分派出来的激活应该呈现为何种样子,属于 module:DropdownMenu/useMenuPress 的职责范围,而不是这里。

内容边界

本记录不会重复源代码中编写的 hook 签名或选项默认值、所属组件的结构、主题或条目语义、打开菜单内部的按下模型、图层定位与关闭规则,或实现步骤。它会链接到各自的权威出处。

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