DropdownMenuItem 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个用于操作或目的地的复合指针菜单行,带有标签、支持内容、禁用状态、破坏性绘制、可选的关闭抑制、根元素输入和转发的 ref。 |
| 行为 | 父级菜单拥有漫游焦点和键盘激活;该行拥有点击顺序、禁用抑制、选中时关闭、目的地交接、悬停聚焦及其可见内容组合。 |
| 最终用户影响 | 操作和目的地保持键盘、指针和浏览器链接行为,而不可用的行保持惰性,破坏性操作保持可识别。 |
| 构建者影响 | 目的地使用 href;支持内容保持非交互性;hasCloseOnSelect=false 保留用于原地结果反馈。 |
| 兼容性/就绪状态 | 记录已发布行为;无 API 变更;禁用行获得 tabindex="-1"(FR7)。 |
| 审查检查 | 拒绝嵌套控件、禁用激活、丢失目的地安全性、破坏的修饰键点击行为、丢弃的根元素输入、第二个键盘所有者,或状态/目标反映移出该行。 |
| 治理规则 | family:navigation-destinations/FR1–FR5;architecture:public-component-api/INV5–INV9;architecture:component-theming-surface/INV3–INV6;spec:AST-020/FR1,FR2,FR6,FR15。 |
此表是审查投影;下文的正文是权威依据。
意图¶
DropdownMenuItem 在 DropdownMenu 的指针呈现中渲染一个复合模式行。它拥有行元素、内容插槽、操作与目的地分支、激活顺序、禁用与破坏性状态、根元素组合,以及 dropdown-menu-item 主题目标。DropdownMenu 拥有周围的菜单、键盘集合、焦点移动、键入即查、呈现选择和关闭生命周期。
兼容性与迁移¶
- 已发布默认值保留:是。
- 兼容性类别:记录已发布行为;无公共 prop 或导出变更;禁用行获得
tabindex="-1"(FR7)。 - 受控/不受控行为:不适用。
- 迁移决策:无。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 一个
role="menuitem"根元素及其标签、描述、图标、末尾内容、禁用状态、破坏性变体、ref、支持的主机输入和样式输入。 - 操作回调顺序和
hasCloseOnSelect行为。 - 链接行渲染、目的地交接、修饰键/中键点击保留、目标与关系处理,以及禁用链接的惰性。
- 指针悬停聚焦以及该行的按下/悬停/聚焦绘制。
dropdown-menu-item目标及其大小/变体状态反映。
不拥有 / 非目标
- 菜单命名、打开/关闭状态、焦点进入、漫游焦点、键入即查和键盘点击合成 — 由 DropdownMenu 及其共享 hooks 拥有。
- 触控和 bottom-sheet 行渲染 — 父级呈现将那些行委托给 List。
- 目的地接收和阻止 — 由
family:navigation-destinations拥有。 - 标签、描述或末尾内容中的交互式控件。控件应位于菜单旁边或作为单独的行。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 行行为 | action;destination | 运行回调,或从该行自身暴露浏览器/路由器目的地。 | 每个启用的行 | action | 组件与导航系列 | 稳定 | 被阻止的目的地是惰性的;禁用链接没有 href。 |
| 可用性 | enabled;disabled | 控制该行是否可激活;禁用行仍可接受键盘焦点(FR7)。 | 每一行 | enabled | 组件与父级菜单 | 稳定 | 禁用状态抑制激活和目的地,但不抑制键盘焦点。 |
| 关闭策略 | close;remain open | 成功激活是否关闭父级菜单。 | 操作行和目的地行 | close | 组件 | 稳定 | 省略即关闭。 |
| 视觉状态 | default;destructive;hover;focus;press;disabled | 绘制行含义和交互状态,而不改变 menuitem 语义。 | 指针行 | default | 组件 | 稳定 | 未知变体由公共类型拒绝。 |
| 根表面 | ref;DOM/data/ARIA;class/style/xstyle/events | 扩展行根部,同时保留组件拥有的角色和键盘状态。 | 每个指针行 | 省略 | 公共组件 API | 稳定 | 接受的输入组合;拥有的角色/制表位保持固定。 |
行为和布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 指针行暴露一个 role="menuitem" 根元素。标签、描述、图标和末端内容是该行的呈现性内容,而不是嵌套控件。 |
spec:AST-020 FR15;当前源码和文档 |
| FR2 | 启用状态下的激活先运行行回调,再进行可选关闭。禁用行暴露 aria-disabled=true,移除链接目标,且既不运行回调也不关闭。 |
当前行为和测试 |
| FR3 | 目标行通过 LinkProvider 渲染为链接根元素。普通激活运行回调,然后关闭并导航;带修饰键的点击不运行回调,关闭菜单(hasCloseOnSelect),然后运行调用方的 onAuxClick;被阻止的协议保持惰性。 |
family:navigation-destinations FR1–FR5;当前测试 |
| FR4 | 父菜单是唯一的键盘所有者。它合成带修饰键的点击激活、移动焦点并运行输入预测;行在鼠标悬停时自聚焦,且不创建第二个漫游焦点模型。 | architecture:interaction-modality;当前父菜单测试 |
| FR5 | 可见根元素带有 dropdown-menu-item;尺寸和破坏性状态反映在其上(data-size、data-variant);语义令牌在调用方样式输入组合之前负责布局和绘制。 |
architecture:component-theming-surface;当前源码和测试 |
| FR6 | Ref、受支持的主机属性和处理程序、className、style 和 xstyle 到达或在行根元素上组合,而不替换所拥有的角色、Tab 停留点、禁用行为、目标处理或激活顺序。 |
architecture:public-component-api INV5–INV9;当前测试 |
| FR7 | 禁用的菜单行保持惰性,父菜单的键盘按 component:DropdownMenu FR17 所述到达它们。 |
component:DropdownMenu FR17,DEC-11 |
| FR8 | 键盘焦点在每一色彩模式下于行内部绘制共享焦点环,按焦点环自身宽度内缩;强制颜色将该环保留为焦点指示器。指针输入后,行仅显示其悬停背景(architecture:interaction-modality INV1),或在手指或笔按住期间显示按压覆盖层(spec:AST-094 FR27);获得焦点的行拥有该指示器(INV3)。 |
当前源码;architecture:interaction-modality INV1、INV3 |
允许的变化¶
- AV1 — 内容。 非交互图标、文本、描述、快捷键、徽章和状态文本可以变化,而不改变行的 menuitem 语义。
- AV2 — 主题绘制。 主题可以重新样式化目标所允许的属性,同时保留可见的状态区分和强制颜色焦点。
- AV3 — 父级尺寸。 父菜单提供
sm、md或lg;行反映该状态,并可以改变其令牌化的内边距。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变化 |
|---|---|---|
| 已启用操作 | 回调执行,随后关闭行为遵循关闭策略。 | 内容、尺寸和视觉变体。 |
| 就地结果操作 | 回调执行且菜单保持打开。 | 标签/末尾内容可以更新。 |
| 禁用操作 | aria-disabled=true;回调、悬停聚焦和关闭均被抑制。 |
内容保持可见。 |
| 目的地 | 单个锚点根元素保留安全目的地和浏览器激活行为。 | 目标、rel、路由器提供者和内容。 |
| 破坏性操作 | 错误角色视觉应用于标签、图标和描述,且不改变行为。 | 其他行内容保持由使用方编写。 |
| 键盘焦点 | 父级焦点落在该行上并保持可见。 | 精确的主题视觉可能有所不同。 |
| RTL / 窄视口 | 逻辑内边距和起始对齐遵循方向,且不产生水平溢出。 | 菜单位置仍由父级决定。 |
变换与优先级顺序¶
- ORD1 — 激活。 禁用守卫 → 浏览器导航分类 → 适用的行回调 → 关闭策略 → 浏览器/路由器导航。
- ORD2 — 根元素组合。 父级尺寸 → 基础行样式 → 变体/禁用状态 → 调用方
xstyle;目标元数据和调用方的 class/style 组合在同一根元素上。
性能与资源¶
- PR1 — 共享按压监听器。 该行共享按压控制器的 window 和 document 监听器;不添加逐行监听器、观察器、定时器或请求。
无障碍契约¶
- AR1 — 菜单项语义。 根元素是一个命名的
menuitem;支持内容不会引入嵌套的交互后代。 - AR2 — 禁用状态。 禁用的行暴露状态,且无法激活或导航。
- AR3 — 键盘所有权。 DropdownMenu 拥有焦点收集和激活;该项在该模型中保持为单行。
- AR4 — 焦点感知。 键盘输入后,聚焦的行在所有颜色模式下(包括强制颜色)在其边缘内绘制共享焦点环;指针输入后,其背景遵循 FR8。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 行 | 一个全宽的操作/目的地目标,具有令牌化内边距和起始对齐。 | 当前源和父级菜单组合 | 主要 | FR1–FR6 |
| 辅助文本 | 描述和末尾内容保持从属于行标签。 | 委派的 Item 布局和当前使用方文档 | 辅助 | FR1 |
| 交互 | 悬停、焦点、按压、禁用和破坏性状态保持可区分。 | 当前源;FR8 | 主要 | FR5、FR8、AR4 |
不记录组件本地的视觉决策。
家族与系统关系¶
family:navigation-destinations拥有目的地接受和阻止方案行为;此组件提供承载目的地的行。architecture:public-component-api拥有根输入组合、引用和已发布兼容性。architecture:component-theming-surface拥有目标放置和状态反映。architecture:component-test-sufficiency拥有相应的可观察证据。architecture:interaction-modality和 DropdownMenu 拥有父级键盘行为。spec:AST-020提供 WCAG/APG 采纳和证据层边界。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1、AR1 | DropdownMenu.test.tsx 复合模式用例("将 JSX 子元素渲染为菜单项"、"在项标签后渲染 endContent");Menu.a11y.test.tsx 菜单绑定用例 |
带内容的操作行 | 不作为 menuitem 的行或丢失内容的行将失败。证据缺口:没有测试断言支持内容不包含嵌套控件。 |
audit:DropdownMenuItem/semantics |
| FR2, AR2, ORD1 | DropdownMenu.test.tsx 条目用例(“点击条目时调用 onClick”、“条目激活后关闭菜单”、“条目选择不关闭时保持菜单打开”、“禁用时不调用 onClick”)、“禁用的复合条目具有 aria-disabled”,以及“禁用的 href 行不渲染地址” |
启用、禁用、关闭与保持打开 | 禁用时触发回调、缺少 aria-disabled、忽略策略的关闭行为,或禁用的行带有地址,均视为失败。证据缺口:没有测试断言回调先于关闭的顺序。 |
audit:DropdownMenuItem/behavior |
| FR3 | DropdownMenu.test.tsx 的“DropdownMenuItem href”与“链接行——浏览器自身的点击”用例;以及“在链接行上中键点击会运行调用方的 onAuxClick 并仍然关闭菜单” |
普通、修饰、中键、右键点击;被阻止的目标 | 非锚点行、运行了回调的修饰点击、未关闭菜单的中键点击,或实际存在的被阻止目标,均视为失败。 | audit:DropdownMenuItem/behavior |
| FR4, AR3 | DropdownMenu.test.tsx 键盘访问用例(“将焦点移动到鼠标悬停的条目,保持单一高亮”、“禁用条目在悬停时不移入焦点”、“非鼠标(触摸)指针不移入焦点”)以及“在调用方的 onPointerMove 之外,保留行自身的角色、Tab 停靠点与悬停焦点” |
鼠标悬停、触摸、禁用 | 出现第二个高亮、禁用行或触摸状态下获得悬停焦点,或丢失 Tab 停靠点,均视为失败。 | audit:DropdownMenuItem/accessibility |
| FR5 | DropdownMenu.test.tsx 破坏性变体用例;themingTargets.test.ts |
默认与破坏性;data 模式与复合模式 | 缺少 data-variant 即失败;渲染出的类不在文档化目标中即失败。证据缺口:没有测试断言 dropdown-menu-item 类或 data-size。 |
audit:DropdownMenuItem/theming |
| FR6 | DropdownMenu.test.tsx ref 与宿主属性用例(“ref 到达 menuitem 元素”、“将 aria-*、data-* 和 id 放在行根元素上,包括链接行”、“运行调用方附加的 DOM 处理器,例如放置目标”) |
ref;宿主属性;调用方处理器 | ref、属性或处理器丢失即失败。证据缺口:没有测试断言行上的 className、style 或 xstyle。 |
audit:DropdownMenuItem/api |
| FR7 | DropdownMenu.test.tsx 禁用行的键盘用例(component:DropdownMenu FR17) |
禁用行 | 禁用行被激活、关闭菜单,或被父级的箭头键或 type-ahead(输入跳转)跳过,均视为失败。 | audit:DropdownMenuItem/accessibility |
| FR8, AR4, PR1 | DropdownMenuForcedColors.test.tsx(每行的 :focus-visible 焦点环与 token 内缩);DropdownMenuAudit.a11y.chromium.spec.ts 强制颜色帧 |
操作行与破坏性行;浅色、深色、强制颜色 | 键盘输入后行没有焦点环,或焦点环未按环宽内缩,均视为失败。证据缺口:没有测试断言已绑定的监听器。 | audit:DropdownMenuItem/visual |
| RTL | apps/storybook/rtl-audit/verified-not-applicable.json 中的 DropdownMenuItem 条目 |
LTR 与 RTL | 源哈希一旦更改,凭证校验即失败。 | audit:DropdownMenuItem/rtl |
当前状态影响¶
无。
决策日志¶
无组件局部决策。
未决问题¶
无。
内容边界¶
本文件不重复使用方属性表/示例、当前审计分数、截图矩阵、实现步骤或组件族/系统规则。它链接到它们的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx