跳转至

NavHeadingMenu 组件契约

契约概览

领域 契约
公共契约 NavHeadingMenu 支持 children、size(sm、md、lg;默认 md)和 minWidth;NavHeadingMenuItem 支持 label、description、icon、href、onClick 和 isDisabled;目标为 nav-heading-menu 和 nav-heading-menu-item,并带有 size 状态。
行为 标题弹出层内由 menuitem 行组成的 role="menu" 列表,支持方向键、Home、End、typeahead、Enter、Space 和 Escape。选择启用项会执行该项,并在宿主标题提供关闭动作时关闭标题菜单。
终端用户影响 用户可通过指针或键盘从标题菜单切换产品或账户;键盘和 typeahead 可以到达禁用行,这些行会被宣告为已禁用,且不会执行任何操作(FR6)。
构建方影响 无。
兼容性/就绪状态 记录已发布行为;无 API 变更;禁用项获得 tabindex="-1"(FR6)。存在四个实现缺口(参见“当前状态影响”)。
评审检查 拒绝以下情况:因调用方 props 丢失 menu/menuitem 角色;键盘移动或 typeahead 跳过禁用项;禁用项执行操作或关闭菜单;或调用方 onKeyDown 静默禁用键盘模型。
治理规则 family:navigation-destinations FR7;architecture:interaction-modality;architecture:component-theming-surface;architecture:layer-runtime。

此表是评审投影;下文正文具有权威性。

意图

NavHeadingMenu 在 SideNavHeading 或 TopNavHeading 弹出层中呈现可选择的操作。它拥有菜单列表、键盘模型以及每个项的行。NavMenu.doc.mjs 将 NavHeadingMenu 和 NavHeadingMenuItem 一起记录,而 NavHeadingMenuItem 没有自己的消费者文档,因此本记录涵盖两者。

兼容性与迁移

  • 已发布的默认值保留:对于禁用项为 no:键盘可到达禁用项,且该项带有 tabindex="-1"(FR5、FR6),这是 component:DropdownMenu DEC-11 下的缺陷修复(所有者决策,2026-11-04)
  • 兼容性类别:记录已发布行为;无公共 API、样式或目标变更;禁用项获得 tabindex="-1"(FR6)
  • 受控/非受控行为:不适用
  • 迁移决策:无

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

当前状态影响

  • 禁用链接项仍会导航。 带 href 的禁用 NavHeadingMenuItem 保留其链接目标且不取消点击,因此指针点击仍会导航,即使该项报告 aria-disabled 并跳过其 onClick。family:navigation-destinations FR7 要求成员保持自己的禁用语义,spec:AST-085 FR2 要求禁用控件阻止导航。
  • 文档描述的合成方式嵌套了两个菜单。 按消费者文档指示作为 SideNavHeading 或 TopNavHeading 的 menu 传入时,NavHeadingMenu 的 role="menu" 直接位于标题自身 role="menu" 包装器内部。WAI-ARIA 1.2 允许 menu 仅拥有 menuitem 系列项和组,因此辅助技术会遇到嵌套在菜单中的菜单。
  • 菜单没有自己的名称。 除非调用方传入 aria-label,否则 NavHeadingMenu 的 menu 没有可访问名称;在标题内部,只有标题的包装器 menu 被命名。spec:AST-020 FR15 采用的 APG 菜单模式会为每个菜单命名。
  • 焦点仅通过填充显示。 项会移除轮廓,并用悬停填充标记焦点;它不使用 architecture:interaction-modality 提供的共享焦点轮廓。

所有权边界

拥有

  • 菜单容器、菜单语义、键盘移动、typeahead 以及当前的 nav-heading-menu 目标。
  • 每个项的操作/链接行、选择处理、尺寸处理以及当前的 nav-heading-menu-item 目标。
  • 包含文本渲染或调用方渲染标签路径以及可选描述的内容布局。

不拥有 / 非目标

  • 图标图形和 icon 目标 — 对于通过 Icon 渲染的值,委托给 component:Icon。
  • 字符串标签和描述的排版及其 text 目标 — 委托给 component:Text。
  • 非字符串标签内容 — 由调用方拥有。
  • SideNavHeading 或 TopNavHeading 的触发器、弹出表面、定位、关闭生命周期或关闭状态所有权 — 由 component:SideNavHeading 和 component:TopNavHeading 拥有。
  • 目标接受与阻止 — 由 family:navigation-destinations 拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Size sm、md、lg 菜单最小宽度(160、200、240 像素)和项目内边距。 通过上下文作用于菜单和每个项目。 md component:NavHeadingMenu 稳定 TypeScript 拒绝其他值。

行为与布局契约

ID 不变量 依据
FR1 NavHeadingMenu 渲染一个带有 role="menu" 的 Menu div,同时携带当前 nav-heading-menu target、size、转发的 ref、data-testid 及其他 DOM props;调用方 props 不能替换该 role。minWidth 会覆盖 size 的最小宽度。 当前源代码、文档和测试
FR2 NavHeadingMenuItem 渲染一个带有 role="menuitem" 和当前 nav-heading-menu-item target(包含菜单的 size)的 Item;当提供 href 时,以 LinkProvider 链接(否则为 <a>)呈现,否则为 div。调用方 props 不能替换其 role、tab 索引或禁用状态。 当前源代码、文档和测试
FR3 可选的 Icon 渲染图标委托给 Icon 的 icon target。字符串标签和所有描述通过 Text 的 text target 渲染为单行;非字符串标签则直接作为调用方拥有的内容渲染。 当前源代码和 target 文档
FR4 宿主 heading 拥有弹窗运行时。当它提供关闭回调时(TopNavHeading 和折叠状态的 SideNavHeading),NavHeadingMenu 会在 Escape 和成功选择 Item 时调用该回调;展开状态的 SideNavHeading 不提供回调,因此选择后菜单保持打开(component:SideNavHeading FR7)。 当前源代码和测试
FR5 项目(包括禁用项目)可获得焦点,但不是 Tab 停靠点。在独立菜单中,ArrowDown 和 ArrowUp 每次移动一个项目(包括禁用项目)并可循环;Home 和 End 跳转到第一个和最后一个项目;键入一个字符会移动到匹配的项目(包括禁用项目)(FR6、component:DropdownMenu FR17);Enter 或 Space 激活当前聚焦的项目。 当前源代码和测试
FR6 激活一个已启用项目会运行其 onClick,然后运行关闭回调;已禁用项目带有 aria-disabled="true",如同已启用项目一样,MUST 保持在 Tab 顺序之外但仍然可聚焦(spec:AST-085 FR1),并且可通过键盘移动和 typeahead 到达,如 component:DropdownMenu FR17 所述(所有者决定,2026-11-04,component:DropdownMenu DEC-11),但不会运行 onClick 或关闭菜单。 当前源代码和测试
FR7 菜单上的调用方 onKeyDown 首先运行;除非该调用方在某个尚未被任何项目处理程序取消的事件上调用 preventDefault(),否则键盘模型仍会运行;项目处理程序的取消不会停止箭头导航。 当前源代码和测试
FR8 在打开的菜单中,按下(手指、触控笔或鼠标)落在启用项目上并在项目间滑动时,会在抬起时所处的项目上触发一次操作,通过该项目自身的激活机制,高亮跟随指针;在外部抬起不作用于任何项目,鼠标在外部释放会关闭菜单。菜单为此采用 module:DropdownMenu/useMenuPress(family:action-groups FR1–FR5;module:DropdownMenu/useMenuPress DEC-7)。按在非项目的调用方内容上,以及对链接项目的 Ctrl、Cmd 或 Shift 点击或中键点击,仍由该内容或浏览器自身处理,键盘和辅助技术行为不变。 当前源代码和测试

允许的变化

  • 项目可以渲染为链接或回调操作,并且可以启用或禁用,而不改变结构所有权。
  • 图标可以不存在。标签可以采用通过 Text 渲染的字符串路径,或直接渲染为调用方自有内容的非字符串路径。项目描述可以不存在,存在时通过 Text 渲染。
  • 菜单大小和最小宽度可以变化,而不会创建独立的结构部分或目标。

代表性状态

状态 必需的不变量 允许的变化
链接项目 项目是带有 menuitem 语义及其当前目标的锚点。 目标、文本、描述和图标可以变化。
操作项目 项目是带有 menuitem 语义及其当前目标的 div。 选择回调可以变化。
禁用项目 项目保持存在并反映禁用语义。 键盘移动和 typeahead 可到达;激活时不执行任何操作(FR6)。
字符串标签项目 文本渲染的项目标签委托给 Text 的当前目标。 标签值、目标、描述和图标可以变化。
自定义标签项目 调用方渲染的项目标签仍归调用方所有。 调用方控制非字符串标签内容。
带描述项目 项目描述委托给 Text 的当前目标。 描述内容可以变化或不存在。

转换和优先级顺序

  • ORD1 — 菜单宽度。 minWidth,然后是尺寸的最小宽度。
  • ORD2 — 键盘。 调用方 onKeyDown,然后是菜单键盘模型(FR7)。

性能和资源

  • 无资源规则。

可访问性契约

  • AR1 — 菜单语义。 一个 menu 包含 menuitem 行(FR1、FR2)。它仅通过调用方的 aria-label 命名;在标题内部,标题命名其自身的包装 menu,而不是此菜单(当前状态影响)。
  • AR2 — 键盘。 FR5 和 FR6。
  • AR3 — 禁用。 禁用项目以禁用状态暴露,可通过键盘移动和 typeahead 到达,并且是惰性的(FR6)。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
菜单 使用菜单语义和键盘导航对导航标题操作进行分组。 当前源代码和公开文档 突出 FR1、FR4
项目 呈现一个可选择的操作或导航目标。 当前源代码和公开文档 突出 FR2
Icon 在标签之前呈现可选的 Icon 所属图形。 component:Icon 辅助 FR3
文本渲染的项标签 通过 Text 的正文处理呈现字符串标签。 component:Text 突出 FR2, FR3
调用方渲染的项标签 通过调用方拥有的内容直接呈现非字符串标签。 调用方提供的内容 视上下文而定 FR2, FR3
项描述 通过 Text 的辅助处理呈现可选的辅助内容。 component:Text 辅助 FR2, FR3

菜单是弹层内容,而非弹层宿主。SideNavHeading 或 TopNavHeading 负责层生命周期,并通过 context 提供关闭回调。

主题化解剖结构

{
  "Menu": {"target": "nav-heading-menu"},
  "Item": {"target": "nav-heading-menu-item"},
  "Icon": {
    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
  },
  "Text-rendered item label": {
    "delegatesTo": {"owner": "component:Text", "target": "text"}
  },
  "Caller-rendered item label": {
    "none": {
      "reason": "intentional: Non-string label content is rendered directly and remains caller-owned"
    }
  },
  "Item description": {
    "delegatesTo": {"owner": "component:Text", "target": "text"}
  }
}

家族与系统关系

  • architecture:component-theming-surface 负责解剖结构的资格认定、本地目标映射、组件委托以及事实性的 none 处置。
  • architecture:icon-resolution-and-component-slots 负责 Icon 插槽解析;本记录陈述当前 Icon 的委托关系。
  • architecture:layer-runtime 负责父级导航标题所使用的共享弹层宿主生命周期。NavHeadingMenu 只拥有其菜单行为,并消费标题提供的关闭回调。
  • architecture:public-component-api 负责稳定的 props 与子组件表面。
  • family:navigation-destinations 负责为 NavHeadingMenuItem 的 href 维护共享的接受/阻止结果;spec:AST-005/DEC-1 要求原生与自定义路由的项路径都保留该结果。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1, FR2 NavHeadingMenu.test.tsx 的 role、render、link 与 disabled 测试套件 包含 link、action 与 disabled Item 的菜单 移除菜单/项语义、内容或当前渲染分支会导致现有的 role、标签、属性和文本检查失败。 audit:NavHeadingMenu/anatomy
FR3 NavHeadingMenuItem 源码检查以及 Icon 和 Text 目标元数据 Icon、字符串标签、调用方渲染的标签以及描述路径 源码证明 Icon 插槽委托、条件标签渲染和 Text 包裹的描述;聚焦测试断言字符串和描述内容,但不断言目标位置或自定义标签的所有权。 audit:NavHeadingMenu/theming
FR4–FR7 NavHeadingMenu.test.tsx 的 context、键盘、disabled 与 pass-through 测试套件 选择、Escape、方向键、Home/End、typeahead、disabled、调用方处理器 破坏关闭回调的消费、键盘行为或 role 优先级会导致聚焦的交互断言失败。 audit:NavHeadingMenu/behavior
目标清单 源码检查与 themingTargets.test.ts Menu、Item 以及委托的 Icon 目标 运行时与文档中目标元数据的不一致会导致目标验证失败。 audit:NavHeadingMenu/theming
主题化解剖结构映射 scripts/check-knowledge.mjs 规范解剖结构以及两个当前本地目标 缺失、多余、带前缀或过时的映射会导致仓库验证失败。 audit:NavHeadingMenu/theming
FR8 NavHeadingMenu.test.tsx 的 action-group 测试套件(触摸和鼠标滑动) 跨项的触摸和鼠标滑动;一个 disabled 项;不可拖动的 link 项 移除该采用行为会导致滑动测试失败。 —
RTL 关系 RTL 审计策划的 D2 目标(apps/storybook/rtl-audit/targets.json)作用于 NavMenu / With icons 菜单项图标及其标签;LTR 和 RTL 图标不在其标签的内联起始位置时,则不满足 D2。 audit:NavHeadingMenu/i18n-rtl

从源码读取,目前尚无针对性测试:

  • FR1:转发的 ref,以及菜单角色优先于调用方 props。
  • FR2:nav-heading-menu-item 目标和 LinkProvider 链接。
  • FR3。
  • FR5:启用项可以聚焦,但不是 Tab 停止点。
  • FR6:禁用项不会关闭菜单。
  • FR4、FR5 和 AR1(在 SideNavHeading 或 TopNavHeading 中)。
  • Menu 和 Item 目标在主题映射中的位置。

决策日志

未记录任何组件级决策。

未决问题

无。

内容边界

本文件不重复使用者 props 表、示例、键盘或层算法、实现步骤或系统规则,而是链接到它们的所有者。

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