useMenuPress 模块契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 新的公共 hook useMenuPress 及其驱动的纯 menuPressStep 状态机,从 @astryxdesign/core/hooks 导出;标记 data-astryx-menu-press 出现在每个挂载它的菜单或 listbox 根元素上;该 hook 的触发器部分(onTriggerPress、triggerProps、isTriggerClickFromPress、longPressDelayMs)在 0.6.6 中发布。DropdownMenu、ContextMenu、DropdownMenuSubMenu 或 Selector 的消费者 prop 均无变化。 |
| 行为 | 指针松开时所在的行即为生效的行;高亮跟随按住不放的鼠标;鼠标在外部松开会关闭菜单;浏览器针对受跟踪手势产生的游离点击(stray click)永远不会生效;菜单根元素通过 overflow 声明 touch-action。在每一个主指针下,手指或笔的按压遵循 spec:AST-094 FR26–FR30。建议方案(FR8、DEC-4):鼠标在按下时打开 DropdownMenu,并在打开时的松开动作上采用 settle 规则。 |
| 最终用户影响 | 手指落在一个菜单行上、在另一行抬起时,会在第二行上生效一次,而不是第一行;在打开的菜单内拖动会选择松开的位置;鼠标在外部松开会关闭菜单,手指则不会。建议方案:鼠标可以在一次手势中按下触发器、拖入菜单并在某一行上松开。手指下的打开行为遵循 spec:AST-094 FR29。键盘行为与子菜单悬停保持不变。 |
| 构建者影响 | 对五个界面的消费者而言没有影响:他们自行挂载该模型。组件只有在满足下方资格条件时才可以采用此模型,且其组件契约在挂载 useMenuPress 之前 MUST 明确指明此模块及受管辖的界面。构建者需提供可用行选择器和 touch-action 声明。 |
| 兼容性与就绪状态 | 新增公共 hook;现有消费者 prop 不变;已发布的键盘行为不变。已发布行为的变化:FR6 的鼠标行按下通过 press 控制器(spec:AST-094 DEC-21;证据待补),DEC-3(当前;鼠标在菜单外部松开会将其关闭)以及建议方案 DEC-4(鼠标在按下而非点击时打开菜单;在手指下,spec:AST-094 FR29)。jsdom 证据已覆盖 FR1–FR7,真实 Chromium 证据覆盖触摸平移、手指滑动及其游离点击;FR10 的静止手指、FR11 的交接以及 AR5 的单次打开与关闭需要真实浏览器证据;本模块不要求 iOS WebKit 证据。负责人:当前适用于 FR1–FR7、DEC-3、DEC-6、DEC-7(cixzhang,2026-10-02)以及 FR10、FR11、AR5、DEC-8(cixzhang,2026-10-25);FR8 和 DEC-4 在本变更中提出,等待同一负责人(OQ1)。 |
| 审查检查 | 拒绝在 pointerdown 上触发,或在已跟踪释放后由浏览器 click 触发的行;拒绝一次手势中对某一行的第二次激活;拒绝同时点亮两行的高亮;拒绝手指在外部释放时关闭菜单,或鼠标在外部释放时保持菜单打开的情况;拒绝没有 touch-action 声明的菜单根节点;拒绝其 listbox 为高亮而取得 DOM 焦点的选择器;拒绝在指针进入菜单或按压稳定之前就作用的打开释放;拒绝其 press 和 click 在同一次手势中均进行切换的触发器。 |
| 治理规则 | architecture:interaction-modality INV2–INV4(每种模态一条可操作路径,悬停作为增强,菜单可随指针移动焦点);architecture:public-component-api 用于新的公开 hook;architecture:layer-runtime 用于模型保留的原生轻量关闭;family:overlay-dismissal 用于 Escape 键顺序,本模块不改变该顺序。 |
此表是审查投影;以下正文具有权威性。
意图¶
Astryx 菜单和选择器此前自行回答基本的指针问题,且没有一个会关注手指:当浏览器报告 click 时,行才会触发,而触摸浏览器会将 click 指向触摸开始的那一行。从一行滑到另一行再抬起,触发的仍是第一行。本模块拥有一个可复用的按压模型:由释放决定,高亮跟随指针,并且(此处提议)鼠标在按下时打开。这是供显式采用它的组件使用的设计系统行为,因此任何产品都无需为符合条件的表面单独携带按压控制器。
本模块仅对按压模型作出契约。菜单结构、主题、呈现策略、键盘导航和条目语义仍由所属组件记录负责;通过键盘打开触发器由渲染触发器的组件负责,手指按压下的打开遵循 spec:AST-094 FR29。
采用资格¶
只有当以下所有条件都成立时,组件才可以采用本模块:
- 其打开的表面呈现离散的操作行或选项行。
- 按住指针并跨过这些行,意味着预览最终的选择。
- 释放指针时,能识别出一个明确无歧义的已启用行。
- 拖拽没有单独的组件含义,例如重新排序、scrubbing 或直接操作。
资格并不会导致采用。每个采用组件的契约 MUST 显式命名 module:DropdownMenu/useMenuPress 以及它所治理的表面和声明。导出 useMenuPress 并不会使每个符合条件的组件都成为采用者。
兼容性与迁移¶
- 已发布默认值保留情况:
no适用于两种行为:DEC-3(鼠标在菜单外部释放现在会将其关闭),以及未设置的longPressDelayMs,其已发布的 500 ms 等待在手指下让位于spec:AST-094FR29 的时序;yes适用于每个消费者 prop 以及每个 item、divider、section 和呈现 API - 兼容性类别:新增的公开 hook 和类型;菜单家族内部的行为变更
- 迁移决策:
module:DropdownMenu/useMenuPress/DEC-3;提议的module:DropdownMenu/useMenuPress/DEC-4(待所有者审核);spec:AST-094FR25(需要已发布 500 ms 等待的调用者传入longPressDelayMs: 500)
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
负责
- 手势状态机(
menuPressStep):跟踪、释放与取消; 拟议:触发按下、打开,以及 settle 规则。 - 通过
pointerId对进行中的手势进行文档级指针跟踪。 - 在指针按住期间移动高亮:菜单中使用 DOM 焦点,选择器中使用调用方提供的回调。
- 在释放时像行自身的点击那样激活该行,使用释放时的按键和修饰键,并吞掉浏览器为该手势产生的多余点击。
- 当
pointercancel、第二个指针或窗口失焦时,不做任何处理地结束手势。 - 当按下被跟踪在溢出的菜单中时,进行边缘自动滚动。
- 拟议:在鼠标按下和手指按住时打开父菜单,并告知触发器该手势的点击已消耗。
- 菜单根上的标记
data-astryx-menu-press。
不负责 / 非目标
- 整体菜单结构、呈现解析、菜单项渲染、主题目标 — 由
component:DropdownMenu、component:ContextMenu、component:Selector负责。 - 行在执行操作时是否关闭菜单 — 由行负责(
hasCloseOnSelect、复选框和单选项目)。 - 滚动。浏览器通过菜单根声明的
touch-action决定手指何时滚动;本模块从不重新实现滚动,也从不监听scroll。 - 原生轻触关闭、Escape 顺序和焦点陷阱 — 由
architecture:layer-runtime和family:overlay-dismissal负责。 - 通过键盘从触发器打开菜单 — 由渲染触发器的组件负责;在手指操作下,
spec:AST-094FR29 管辖它。 - 键盘导航、typeahead 以及 Enter/Space 激活 — 由
useListFocus、useTypeahead和组件记录负责。 - 悬停打开子菜单弹出层 — 由
useMenuHover负责。 - 在菜单之外以及 Selector 和 MultiSelector 的选项之外,跨一组操作跟踪按住的指针 — 由
architecture:interaction-modality这个内部模块负责,INV13 为family:action-groups成员命名了该模块;本模块只覆盖菜单和这些选项。 - 菜单内的鼠标右键:不对其建模。
公共 API 与概念¶
| Concept | Closed values or states | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
| 手势阶段 | idle、tracking;拟议 triggerPress、open |
进行中的按下所处的阶段 | idle |
module:DropdownMenu/useMenuPress |
稳定 |
| 效果 | none、highlight、clear、act、settle;拟议 open |
单个事件让宿主做什么;open 要求触发器在指针按住下打开菜单;settle 携带 stray(吞掉浏览器的点击)和 dismiss(关闭菜单) |
— | module:DropdownMenu/useMenuPress |
稳定 |
| 指针类型 | mouse、touch、pen |
手势自身的指针;touch 和 pen 算作“手指” |
来自事件 | module:DropdownMenu/useMenuPress |
稳定 |
| 启用行选择器 | 调用方字符串 | 释放可作用的行;根内部其他任何内容都不会高亮 | 必需 | module:DropdownMenu/useMenuPress |
稳定 |
| 高亮 | DOM 焦点,或调用方回调 | 一个高亮的行;菜单中使用带 preventScroll 的焦点,选择器中使用 aria-activedescendant |
焦点 | module:DropdownMenu/useMenuPress |
稳定 |
| 多余点击窗口 | 400 毫秒,或下一次 pointerdown |
在被跟踪的释放之后,浏览器的点击仍会被吞掉多久 | MENU_PRESS_STRAY_CLICK_MS |
module:DropdownMenu/useMenuPress |
稳定 |
| settle 时间 | 300 毫秒 | 拟议:一个用于打开的按下在释放可作用之前必须持续多久 | MENU_PRESS_SETTLE_MS |
module:DropdownMenu/useMenuPress |
拟议 |
| 长按延迟 | 设置后为释放后的 500 ms;未设置时,如 spec:AST-094 FR29 所述(固定栏内无延迟;滚动视图中为 150 ms) |
手指按住触发器多久之后菜单才打开。调用方若设置了 longPressDelayMs,则在固定栏和滚动视图中都获得该等待时长,这保持了发布的行为(spec:AST-094 FR25)。 |
longPressDelayMs |
module:DropdownMenu/useMenuPress |
stable |
data-astryx-menu-press |
存在或不存在 | 根元素承载此模型;宿主控制器自身独立存在 | 存在于每个已挂载的根元素上 | module:DropdownMenu/useMenuPress |
stable |
| 激活点击 | click 且 detail: 0,带有释放时的按钮和修饰键 |
模型如何作用于一行,并由 isMenuPressActivation() 标记为同步范围;因此,在菜单行上 detail === 0 单独不再表示“键盘” |
— | module:DropdownMenu/useMenuPress |
stable |
行为契约¶
| ID | 不变式 | 依据 | 验证状态 |
|---|---|---|---|
| FR1 | 一行必须在释放按下操作于其上时生效,绝不能因为按下操作始于该行而生效;从未离开该行的按下操作是该行上的轻点或点击。手指或笔在所有主指针下(spec:AST-094 FR43)改为遵循 spec:AST-094 FR26;鼠标保持此规则。 |
macOS 和 iOS 菜单行为;menuPressGesture.test.ts、useMenuPress.test.tsx |
verify |
| FR2 | 当按下操作在菜单内持续时,高亮行必须是指针所在且已启用的行,并且不得在分隔线、标题、禁用行或菜单外部高亮任何内容。鼠标在未按下按钮时移动也会以相同方式移动高亮(现有的悬停聚焦行为)。手指或笔在所有主指针下改为遵循 spec:AST-094 FR27 和 FR11 的单元格行为特征,而第二个手指会结束该手势(FR4);鼠标保持此规则。 |
architecture:interaction-modality 允许的菜单变体;useMenuPress.test.tsx |
verify |
| FR3 | 始于菜单内并在菜单外释放的按下操作不得作用于任何内容。在鼠标下,菜单随后必须关闭;在手指或笔下,菜单必须保持打开(spec:AST-094 FR28)。 |
DEC-3;useMenuPress.test.tsx、DropdownMenu.test.tsx、Selector.test.tsx |
verify |
| FR4 | 行内容完全适配的菜单必须声明 touch-action: pinch-zoom;需要滚动的菜单必须声明 touch-action: pan-y pinch-zoom 和 overscroll-behavior: contain。两种声明都不允许菜单无法滚动时的单指平移,并且都将双指缩放留给浏览器,因此页面在打开的菜单上方仍可缩放。模型必须将 pointercancel 和第二个指针视为手势结束且不产生任何作用,并且不得重新实现滚动。 |
浏览器滚动所有权;spec:AST-020 FR1 下的 WCAG 2.2 SC 1.4.4;DropdownMenu.test.tsx touch-action 用例、useMenuPress.test.tsx、MenuPinchZoom.a11y.chromium.spec.ts |
verify |
| FR5 | 对于此模型跟踪的手势,浏览器报告的 click MUST NOT 作用于任何行;只有释放才起作用。没有跟踪手势在后的 click,或 detail 为 0 的 click,MUST 像以前一样作用于其目标。swallower 在跟踪到的释放时布防,并在下一个 pointerdown 或游离点击窗口之后撤防。 |
一个手势,一次激活;useMenuPress.test.tsx FR5 套件 |
verify |
| FR6 | 菜单中最多只有一行被点亮。在手指下,一旦指针离开,按下开始所在的行 MUST NOT 保持按下或悬停的外观。手指或触控笔改为遵循 spec:AST-094 FR27 和 FR11,在每一个主指针下;在鼠标下,一行会通过 press controller 立即绘制其按下状态(spec:AST-094 FR11 的 fine-pointer profile,DEC-21)。 |
DropdownMenuItem.tsx 样式;鼠标行按下的 spec:AST-094 DEC-21(未实现:鼠标行仍绘制 :active) |
verify |
| FR7 | 当在可滚动菜单中跟踪按下时,停留在菜单顶部或底部边缘区域内的指针 MUST 使菜单向该边缘滚动,并在行移动时重新读取指针下的行。手指或触控笔改为遵循 spec:AST-094 FR30,在每一个主指针下;鼠标保持此规则。 |
useMenuPress.test.tsx 自动滚动用例 |
verify |
| FR8 | 在鼠标上,DropdownMenu 触发器 MUST 在按下时(button 0,无 Control)打开其菜单,并且从触发器拖入菜单、在启用行上释放的拖动 MUST 作用于该行。打开手势的释放 MUST 仅在指针已进入菜单或按下持续了稳定时间时才起作用;否则无任何动作且菜单保持打开。按下已打开菜单的触发器 MUST 关闭它,并且在同一手势中 MUST NOT 重新打开它。菜单打开时移交给菜单的鼠标指针(FR11)遵循相同的稳定时间规则。 | 提议的 DEC-4;DropdownMenu.test.tsx 按下模型套件,menuPressGesture.test.ts 触发器状态 |
proposed; pending owner review |
| FR9 | 在手指下从其触发器打开菜单,以及打开手指的移交,均受 spec:AST-094 FR29 约束,在每一个主指针下(spec:AST-094 FR43)。 |
spec:AST-094 FR29 |
如 spec:AST-094 所述 |
| FR10 | 在子菜单行上释放的手指 MUST 打开该子菜单,就像该行自身的 click 会做的那样(抬起动作生效,spec:AST-094 FR26;在紧凑型触摸屏上,adaptive 行会钻取进入,FR34);停留在该行上的手指 MUST NOT 打开它。从某行滑到打开的 flyout 的行上的手指,在 ORD1 下会在那里进行选择。 |
DEC-8;DropdownMenuSubMenu.test.tsx 按下用例 |
verify |
| FR11 | 在其他地方按下、随后在菜单打开时被移交给该菜单的指针(例如上下文菜单的长按)MUST 成为打开时的按下。在每一个主指针下,手指仅在移交距离之后才进行选择,该距离按 spec:AST-094 FR33 的计算方式,从菜单打开后看到的第一个位置开始计算;在此之前抬起手指不作用于任何内容,并保持菜单打开。 |
DEC-8;useMenuPress.test.tsx 延续套件 |
verify |
转换与优先级顺序¶
- ORD1 — 一次按下,最内层属主。 菜单内的
pointerdown由承载data-astryx-menu-press的最内层根元素认领(即父级之前的浮出层);最外层根元素决定松开时什么算作“菜单内部”。 - ORD1a(提案) — 根元素旁边的菜单。 承载
data-astryx-menu-press-surface(它指定另一个根元素的id)的根元素,在 ORD1 中嵌套于该根元素,就像根元素 DOM 中的浮出层一样:在其行上的释放属于菜单内部。只有带有 header 或 footer 的子菜单的菜单(根元素将其渲染在自身旁边,component:DropdownMenuFR20)才承载该属性。根元素旁边任何其他内容——比如放置在区域中的 header 字段或选择器——都在菜单外部,正如根元素自身区域一样,那里的选择器仍然是自己的根元素。待属主评审。 - ORD2 — 释放解析。 点下方的已启用行 →
act;在菜单内或触发器上且没有行 →settle(吞掉游离点击,菜单保持打开);外部 → 仅鼠标触发带dismiss的settle。 - ORD3 — 触发器点击(提案)。 按下模型对触发器的打开或关闭先执行;同一个手势(按手势计数器判断)中触发器自身的点击为 no-op;任何其他点击保留其切换行为。
- ORD4 — 激活派发。 模型的激活是一个
click,带有detail: 0,携带释放时的按钮和修饰键,在同步激活标记内派发;重新派发到其内部控件的行会通过;浏览器随后为该手势产生的点击在捕获阶段于 window 处被停止。
性能与资源¶
- PR1 — 每个手势的监听器。 用于
pointermove、pointerup、pointercancel、pointerdown和 windowblur的 document 监听器在按下时挂载,在手势结束时移除;空闲时不存活任何监听器。 - PR2 — 一个吞掉者。 window 捕获阶段
click监听器每个 document 只安装一次,并为每个手势武装。 - PR3 — 自动滚动。 当被追踪的指针停留在溢出菜单的边缘区域时,存在一个 interval;当指针离开该区域、滚动容器到达边缘或手势结束时,它停止。
无障碍契约¶
- AR1 — 菜单中的高亮即焦点。 在菜单中,高亮的行就是获得焦点的行,并通过
preventScroll移动,因此键盘、鼠标和手指共享同一个高亮和同一次绘制;在 Core 的菜单中,按住的指尖或笔会以按下覆盖层绘制其点亮的行(公共useMenuPress调用者获得高亮、点亮行的焦点,并自行给它添加样式);如果行的根元素不获得焦点,则通过其内部控件进行高亮。 - AR2 — 选择器保持其 combobox 焦点。 在 Selector listbox 中,模型驱动
highlightedIndex和aria-activedescendant;DOM 焦点从不移入 listbox。 - AR3 — 辅助技术激活可通过。
detail === 0的click——来自键盘、屏幕阅读器或模型自身派发的——永远不会被吞掉,因此辅助技术照常激活各行。需要将模型的指针激活与键盘激活区分开来的行,应读取isMenuPressActivation()而不是detail。 - AR4 — 选择后的焦点属于组件。 模型像组件自身的 click 一样激活该行;菜单关闭后焦点去向由所属组件记录决定,本模块不改变这一点。
- AR5 — 一次打开,一次关闭。 手指通过
spec:AST-094FR29 的打开、上下文菜单的长按(spec:AST-094FR33)、FR9 的按住按压或点击的 click 打开菜单一次,且没有任何操作撤回已打开的菜单:屏幕阅读器只听到菜单打开一次,并在选择、关闭或 Escape(DEC-8)时只听到关闭一次。
设计关系¶
没有引入任何视觉表现。FR6 将手指的行按压缩定在 spec:AST-094 FR11 的单元格轮廓上,因此单个焦点高亮是手指下唯一被点亮的行;高亮绘制本身是项目组件拥有的现有焦点覆盖层,而在 Core 的菜单中,按住的指尖或笔改用按下覆盖层绘制点亮的行(AR1)。
父级与系统关系¶
component:DropdownMenu拥有聚合菜单结构、呈现解析、目标与项目管道;component:ContextMenu、component:Selector和子菜单浮出层挂载此模块,并通过引用它记录自己的按压认领。architecture:interaction-modality拥有模态跟踪和焦点返回可见性;本模块读取它们,不添加任何模态定义。architecture:layer-runtime拥有原生 light dismiss,本模块将其原样保留:popover="auto"菜单外部的按压仍会通过浏览器将其关闭。当菜单的显示被立即接受时,打开菜单的那次按压即被认领(component:DropdownMenuFR8,spec:AST-003FR11–FR13)。无论该按压在哪里释放,浏览器的 light dismiss 都不会将这次释放解读为关闭,由按压模型决定其行为。在整个按压期间,触发器仍然是该 popover 的 invoker,这正是 layer runtime 的 keep-open props 所使用的机制。在鼠标下,当指针位于触发器上方时,触发器持有指针;当指针位于两者之外时,菜单的 layer 持有指针。当这次显示在等待另一个 popover 操作时,按压模型不再跟踪该按压,因此只有 invoker 保持生效,在触发器之外释放会关闭(与component:DropdownMenuFR8 之间存在差距)。family:overlay-dismissal拥有 Escape 的顺序;此处不变。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 |
|---|---|---|---|
| FR1–FR3, FR5 | menuPressGesture.test.ts(图中每个状态转换一个用例) |
空闲、跟踪;鼠标和触控;在行上、在浏览器界面(chrome)上、在触发器上、外部释放;取消 | 若对按下行执行操作、对杂散点击执行操作,或在手指下关闭,则该转换用例失败 |
| FR1–FR5, FR7, AR1, AR3 | useMenuPress.test.tsx(带有注入的命中测试) |
在另一行上释放、点按、杂散点击、detail: 0、鼠标/手指在外部、pointercancel、第二个指针、自动滚动 |
第二次激活、被吞掉的辅助点击、错误的关闭,或失效的自动滚动都会导致失败 |
| FR1, FR3–FR5 | DropdownMenu.test.tsx、DropdownMenuSubMenu.test.tsx、ContextMenu.test.tsx 按压套件 |
手指在行间滑动、鼠标和手指在外部释放、touch-action、在弹出子菜单(flyout)上释放、根标记 |
每个被移除的行为都会在其对应命名用例中失败 |
| FR1, FR3, AR2 | Selector.test.tsx 按压模型套件 |
手指在另一个选项上释放、手指/鼠标在外部释放、listbox 标记 | 若 listbox 获得焦点、对按下选项执行操作,或在手指下关闭,则失败 |
| FR4(滚动) | MenuPress.a11y.chromium.spec.ts(真实 Chromium) |
Chromium 在溢出菜单中的触摸平移;由 overflow 决定的 touch-action;手指滑动及其杂散点击 | 在 jsdom 中无法证明;若平移对行执行操作,或滑动对按下的行执行操作,则失败 |
| FR4(捏合) | MenuPinchZoom.a11y.chromium.spec.ts(真实 Chromium,手机模拟) |
在行刚好完全显示的菜单上、在可滚动的菜单上,以及在 picker listbox 上进行双指捏合 | 在 jsdom 中无法证明;若捏合使页面最终处于缩放比例 1,或对行执行操作,则失败 |
| FR8(拟议),FR9 | menuPressGesture.test.ts 触发器状态;useMenuPress.test.tsx 触发器套件;DropdownMenu.test.tsx 按压打开用例 |
鼠标立即打开、稳定前/后、取消;按 spec:AST-094 FR29 的手指打开;按压打开 + 拖拽释放、未稳定释放、触发器切换、持续触摸、点按 |
没有在鼠标按压时打开的菜单、执行操作的未稳定释放,或在同一手势中重新打开的触发器,都会导致失败 |
| FR8(拟议) | DropdownMenuOpeningRelease.interaction.browser.spec.ts,Chromium 和 WebKit |
打开后在触发器外释放、在已移开的触发器下方释放,以及在等待后的显示之后释放;在外部稳定释放 | 若未稳定的打开释放被浏览器的 light dismiss(外部轻触关闭)关闭,则失败 |
| FR10, FR11, AR5 | DropdownMenuSubMenu.test.tsx 按压用例,以及一个真实浏览器中手指停留在行上的用例;useMenuPress.test.tsx 延续套件,加上一个真实浏览器交接用例;AR5 的打开和关闭事件计数 |
一个手指在子菜单行上释放并停留;延续的手指、距首个采样点的距离、在此之前抬起、鼠标;菜单的打开和关闭各被观察到一次 | 若子菜单在停留的手指上打开、延续的手指在交接前抬起、打开被撤销,或打开/关闭两次,则失败 |
| ORD1a(拟议) | DropdownMenuSubMenu.test.tsx 按下用例;SubMenuHeaderFooter.a11y.chromium.spec.ts 按下-拖拽用例 |
鼠标在菜单行上按下,在菜单旁渲染的子菜单的某一行上释放;同样的按下在该子菜单的头部字段上释放 | 在此类行上释放却未触发任何操作或导致菜单关闭,或者在其头部字段上释放却触发了操作,均失败。 |
决策日志¶
DEC-3 — 外部释放:鼠标下关闭,手指下保持¶
Reference: module:DropdownMenu/useMenuPress/DEC-3
Decider: vjeux, 2026-09-27
macOS 在鼠标抬起时结束菜单跟踪:在外部释放会关闭菜单。iOS 在从菜单滑出的手指抬起时仍保持菜单展示;之后在外部点击才会关闭。每种指针保留其平台的行为。若两种平台都关闭,滑出的手指将需要第二次手势才能重新打开;若两种平台都保持打开,则会让鼠标用户感到意外。
DEC-4(拟议)— 鼠标在按下时打开,并带有稳定规则¶
Reference: module:DropdownMenu/useMenuPress/DEC-4
Decider: 由 vjeux 提出,2026-09-27;待所有者评审
带拖拽释放的按下打开是 macOS 菜单的做法。在手指下打开遵循 spec:AST-094 FR29 和 DEC-4。打开手势的释放仅在指针已进入菜单或按下已稳定(300 毫秒)后生效,这与原生弹出按钮的行为一致;否则,在指针下打开的菜单会选中一行并非用户所选的项。
DEC-6 — 菜单中的高亮是 DOM 焦点,选择器中则是 aria-activedescendant¶
Reference: module:DropdownMenu/useMenuPress/DEC-6
Decider: vjeux, 2026-09-27
菜单已通过移动悬停焦点来保持单一高亮;手指通过 preventScroll 移动同一焦点,因此键盘、鼠标和触摸共享同一状态和同一绘制;在 Core 的菜单中,按住的手指或笔会用按下覆盖层绘制该行(AR1)。选择器的列表属于 combobox,不得从它那里夺走焦点。手指离开的行不会保留按下绘制,因为那会点亮第二行(FR6)。本记录不决定选中后焦点去向。
DEC-7 — 资格允许采用;组件契约选择加入¶
Reference: module:DropdownMenu/useMenuPress/DEC-7
Decider: cixzhang, 2026-10-02
当组件的展开表面呈现离散的操作或选项行、按住指针在行间移动可预览最终选择、且释放能识别出唯一明确的启用行时,该组件可以采用此模型。拖拽另有含义(如重新排序、擦洗或直接操作)的组件不具备资格。资格本身永远不会导致采用:每个组件契约会明确命名本模块及其所管辖的表面和声明。仅公开 hook 的可用性并不会使组件成为采用者。
DEC-8 — 手指通过抬起打开子菜单,交接的手指即打开按下¶
Reference: module:DropdownMenu/useMenuPress/DEC-8
Decider: cixzhang, 2026-10-25
手指在子菜单行上抬起会打开它,如同一次点击;而停在该行上的手指永远不会打开它,因此子菜单不会从仍在选择中的手指下方打开。在菜单打开时交接给该菜单的手指(例如打开上下文菜单的长按)就是该菜单的打开按下:一旦它移动了交接距离就会进行选择,因此打开菜单的按下本身永远不会选择。手指只能打开一次菜单,且没有任何操作会撤销打开,因此屏幕阅读器只会听到一次打开和一次关闭。
已拒绝:手指停在其行上时打开子菜单。
未决问题¶
- OQ1 — 按下打开是否是菜单家族的触发模型?(
human-design)此项更改所需的唯一所有者决策:拟议的 FR8 和 DEC-4 — 鼠标通过按下并配合稳定规则打开 DropdownMenu。在手指下打开属于spec:AST-094FR29 的规定。在所有者为做出裁决之前,当前记录的 FR1–FR7 独立成立。
此前的浏览器证据问题已解决:触摸平移、手指滑动及其游离点击无法在 jsdom 中执行,而现在已有针对它们的真实 Chromium 证据,见 packages/core/src/DropdownMenu/__tests__/MenuPress.a11y.chromium.spec.ts。cixzhang 于 2026-10-02 裁定,本模块现在或将来均无需 iOS WebKit 证据;真实 Chromium 是证据标准。
内容边界¶
本记录不重复 useMenuPress.doc.mjs 的签名、所属组件的结构或主题、层或关闭规则,也不重复实现步骤。它链接到这些内容的规范所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx