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:DropdownMenuDEC-11 下的缺陷修复(所有者决策,2026-11-04) - 兼容性类别:记录已发布行为;无公共 API、样式或目标变更;禁用项获得
tabindex="-1"(FR6) - 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 禁用链接项仍会导航。 带
href的禁用 NavHeadingMenuItem 保留其链接目标且不取消点击,因此指针点击仍会导航,即使该项报告aria-disabled并跳过其onClick。family:navigation-destinationsFR7 要求成员保持自己的禁用语义,spec:AST-085FR2 要求禁用控件阻止导航。 - 文档描述的合成方式嵌套了两个菜单。 按消费者文档指示作为 SideNavHeading 或 TopNavHeading 的
menu传入时,NavHeadingMenu 的role="menu"直接位于标题自身role="menu"包装器内部。WAI-ARIA 1.2 允许menu仅拥有menuitem系列项和组,因此辅助技术会遇到嵌套在菜单中的菜单。 - 菜单没有自己的名称。 除非调用方传入
aria-label,否则 NavHeadingMenu 的menu没有可访问名称;在标题内部,只有标题的包装器menu被命名。spec:AST-020FR15 采用的 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