跳转至

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