跳转至

SideNavHeading 组件契约

契约概览

区域 契约
公共契约 SideNavHeading,包含 icon、heading、superheading、subheading 及其 *Href 链接、headerEndContent、menu 和 as;目标为 side-nav-heading。
行为 位于 SideNav 顶部的产品标识区块。哪些部分是链接、哪部分打开菜单,由 *Href props 和 menu 决定;在折叠轨道中,它是仅图标的链接、菜单按钮,或带工具提示的图标。
最终用户影响 用户可在展开和折叠轨道中到达产品、套件、账户目标以及产品菜单;屏幕阅读器用户会听到有名称的链接、有名称的触发器和有名称的菜单。
构建者影响 无。
兼容性/就绪状态 发布 FR5 会延迟鼠标和触控笔用户的首次悬停打开;无公共 API 变更。存在七项实现差距(见“当前状态影响”)。
评审检查 拒绝没有名称的折叠图标、包裹在模态对话框中的菜单弹窗、位于 role="menu" 内的标题按钮,或在整块标题链接内渲染的 headerEndContent。
治理规则 architecture:public-component-api INV5;architecture:interaction-modality;family:navigation-destinations。

此表是供评审使用的概览;以下正文为准。

意图

SideNavHeading 在 SideNav 顶部展示产品的图标和名称,并可包含可选的套件和账户行。它负责决定这些部分如何成为链接或菜单触发器、产品菜单弹出层以及折叠轨道形式。消费者用法见 SideNavHeading.doc.mjs。

兼容性与迁移

  • 已发布默认行为保留:no;发布 FR5 会延迟鼠标和触控笔用户的首次悬停打开
  • 兼容性类别:记录已发布行为,但 FR5 的首次打开延迟除外;无公共 API 变更
  • 受控/非受控行为:菜单的打开状态是内部的
  • 迁移决策:无

消费者迁移说明应放在消费者文档和发布说明中。

当前状态影响

  • 标题菜单进入延迟(FR5)。 菜单在首次悬停时立即打开,没有进入延迟。FR5 要求使用共享延迟,仅在从同一导航中另一个已打开菜单交接时才无需等待。

  • 某些配置会丢弃 DOM props。 传递给 SideNavHeading 的其他 DOM props(除 data-testid、className、style、xstyle 和 ref 之外)在菜单配置以及折叠链接和菜单按钮形式中不会到达任何元素。architecture:public-component-api INV5 要求接受的 DOM、data、ARIA 和事件输入到达所属元素。

  • NavHeadingMenu 嵌套了第二个菜单。 标题将 menu 包裹在其自身的 role="menu" 中;NavHeadingMenu 作为文档化的 menu 内容,在其中又添加了一个 role="menu"。WAI-ARIA 1.2 允许 menu 仅拥有 menuitem 系列项目及分组。

  • 链接嵌套在弹出层的标题按钮中。 在展开的“链接加触发器”配置中,弹出层的标题按钮在自身内部重复了 superheading、heading 和 subheading 链接,因此交互内容被嵌套在按钮内部。HTML 禁止在 <button> 内放置交互内容。

  • 打开的菜单重复了标识行。 菜单打开时,其标题按钮会重复显示仍挂载在轨道区块中的图标和文本,导致内容渲染两次。architecture:component-style-authoring INV7 要求内容仅渲染一次。

  • “链接加触发器”形式中的链接也会打开菜单。 承载链接的区块带有菜单的触发器处理程序。使用触摸或键盘时,激活 heading 或 suite 链接既会导航又会打开菜单,并将焦点移动到其第一项。使用鼠标时,将指针移到该区块上会立即在其上方打开菜单,因此点击会落在菜单的标题按钮(及其重复的链接)上,而不是下方的链接上。这两种情况都破坏了 FR2 对链接与菜单触发器之间的划分。

  • 末端内容也会打开菜单。 在两种菜单配置中,headerEndContent 都渲染在带有菜单触发器处理程序的区块内。使用触摸或键盘时,激活其中的控件会运行该控件并同时打开菜单,将焦点移动到其第一项。使用鼠标时,将指针移到链接或末端内容上会立即在整个区块上方打开菜单,因此点击末端内容会落在菜单的标题按钮上,菜单会在指针下重新打开。末端内容中的控件属于调用方,不在 FR2 的触发器区域内。

所有权边界

拥有

  • 标识区块及其链接和触发器配置(FR1–FR4、FR11)。
  • 产品菜单弹出层(FR5–FR7)。
  • 折叠轨道形式(FR8)和焦点轮廓(FR9)。

不拥有 / 非目标

  • 目标接收与阻止 — 由 family:navigation-destinations 拥有。
  • 菜单内容 — 由调用方拥有(通常为 NavHeadingMenu)。
  • 轨道的折叠状态 — 由 SideNav 拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 负责人 稳定性 无效值行为
Configuration plain, whole link, whole link with end content, independent links, whole trigger, links plus trigger 由 *Href 属性和 menu 派生(FR2)。 展开的 rail。 Plain component:SideNavHeading Stable 不适用。

行为与布局契约

ID 不变量 依据
FR1 在展开的 rail 中,该块带有 side-nav-heading,并显示图标、文本列(超级标题、标题行、副标题;纯文本行和菜单配置标题链接在单行上以省略号截断,而通过 Link 组件渲染的行会换行)以及 headerEndContent。当存在 menu 时,标题行先包含标题,然后是 chevron 按钮;没有 menu 时则没有 chevron。 当前源码与测试
FR2 单独使用 headingHref 且没有 menu 时,图标和文本成为一个链接;当存在 headerEndContent 时,该内容位于链接旁边,而不是链接内部。在没有 menu 的情况下,其他 *Href 属性会让每个带有 href 的行成为独立链接,并且被链接的图标由 heading 命名。没有 hrefs 的 menu 会使除 headerEndContent 之外的整个块打开菜单;有 hrefs 的 menu 会让每个带有 href 的行成为独立链接,并且 chevron 按钮以及除 headerEndContent 之外的块其余部分会打开菜单。 当前源码与测试
FR3 图标链接、整个标题链接和菜单配置标题链接使用 as 组件,否则使用 LinkProvider 链接,再否则使用 <a>。辅助行,以及独立链接配置中的标题行,使用 Link 组件,该组件不接收 as。 当前源码与测试
FR4 chevron 按钮由 @astryx.sideNav.heading.openMenu 命名,并且是 popover 的触发器。 当前源码与测试
FR5 在支持悬停的指针上,第一次悬停打开会等待菜单悬停延迟(默认 150 ms,与 TopNavMenu 一样),并且从同一导航中的另一个已打开菜单移过来时,会立即打开它(architecture:interaction-modality INV11;负责人决策,2026 年 11 月 6 日(Cindy);在 design:motion DEC-1 中提出)。悬停打开不会移动焦点。点击会打开它并将焦点移到第一个菜单项;在悬停打开后的 500 ms 内点击会保持它打开;按 Escape 会关闭它并将焦点返回给触发器。 Cindy, 2026-11-06
FR6 该菜单是块下方的非模态 popover,与其起始端对齐;在展开的 rail 中,它与块重叠。它包含一个关闭菜单的标题按钮(其内容见“当前状态影响”),然后是一个由 heading 命名、包含 menu 的 role="menu"。 当前源码与测试
FR7 仅有折叠菜单形式会为 menu 后代提供 NavMenu 项在选中时调用的关闭动作;展开菜单形式则不会。 当前源码
FR8 在折叠的 rail 中,没有 icon 时不渲染任何内容。有 icon 时:headingHref 生成一个以 heading 命名的纯图标链接;否则 menu 生成一个以 heading 命名的纯图标按钮,该按钮是其菜单 popover 的原生调用器;否则图标单独渲染。每种形式都在行内末端显示带有 heading 的工具提示;headerEndContent 和 chevron 被隐藏。 当前源码与测试
FR9 每个可聚焦部分都会绘制共享的焦点轮廓。 当前源码与测试
FR10 在产品菜单的 role="menu" 区域中,按下(手指、触控笔或鼠标)落在某个启用项上并滑过各项时,会对抬起时所在的那一项执行操作,且只执行一次,通过该项自身的激活完成,高亮跟随指针;在区域外抬起则不作用于任何项,鼠标在区域外释放会关闭菜单。菜单为此采用 module:DropdownMenu/useMenuPress(family:action-groups FR1–FR5;module:DropdownMenu/useMenuPress DEC-7)。对非项的调用方内容的按下,以及对链接项的 Ctrl-、Cmd- 或 Shift-点击或鼠标中键点击,都保持为该内容本身或浏览器自身的操作,键盘和辅助技术行为不变。 当前源码与测试
FR11 在两种菜单配置中,chevron 按钮的无障碍名称都包含可见的 heading,因此通过所看到的产品或工作区名称来识别该控件的人会听到该名称(family:buttons FR1;WCAG 2.2 Label in Name)。该名称是一条翻译消息 @astryx.sideNav.heading.openMenu,接收 heading 参数:对于标题 "Acme",英文为 "Acme, Open menu"。每个已发布区域设置的消息都原样保留 {heading}。 当前源码与测试

允许的变化

  • AV1 — 线条。 可以出现任意线条组合;块保持其顺序。

代表性状态

状态 必需的不变量 允许的变化
带有末端内容的整条链接 末端内容位于链接旁边。 —
菜单,无 hrefs 整个块触发;命名的 chevron 按钮。 菜单内容。
带 hrefs 的菜单 链接;chevron 和块的其余部分触发。 —
带菜单的折叠形式 命名的图标按钮;弹出菜单;工具提示。 —
无图标的折叠形式 不渲染任何内容。 —

转换与优先级顺序

  • ORD1 — 折叠形式。 依次为 headingHref、menu,然后才是纯图标。

性能与资源

  • 无资源规则。

可访问性契约

  • AR1 — 命名图标。 没有可见文本的链接或按钮图标通过 heading 命名。
  • AR2 — 菜单语义。 弹出窗口不是模态对话框;role="menu" 仅包裹菜单内容。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
图标 前导产品标记;折叠时单独出现。 当前源码与公共文档 突出 FR1、FR8
标题行 超级标题、标题、副标题。 当前源码与公共文档 突出 FR1
菜单弹出窗口 覆盖该块;标题按钮将其关闭。 当前源码 辅助 FR6

SideNavHeading.doc.mjs 未声明自身的任何结构,因此没有记录结构主题映射。

家族与系统关系

  • family:overlay-dismissal 负责此组件弹出窗口的 Escape 与关闭请求顺序。
  • family:navigation-destinations 负责每个 href 的接受/阻止决策。
  • 在提供关闭操作(FR7)的情况下,NavHeadingMenu 项会关闭此菜单。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1–FR4、AR1 SideNav.test.tsx SideNavHeading 与 headerEndContent 测试套件 每种配置 错误元素、未命名链接或错误放置的末尾内容将失败。 audit:SideNavHeading/behavior
FR5 SideNav.test.tsx SideNavHeading 悬停/点击防护套件。证据空白:没有针对首次打开延迟或交接的测试 悬停、点击、延迟点击、Escape 防护丢失或焦点返回失败。 audit:SideNavHeading/behavior
FR6、AR2 SideNav.test.tsx 菜单弹出窗口语义套件 整个触发器;混合;折叠 对话框包装器或错位的菜单角色失败。 audit:SideNavHeading/accessibility
FR8 SideNav.test.tsx SideNavHeading 折叠套件 链接、菜单、纯文本、无图标 缺少名称、工具提示或调用器将失败。 audit:SideNavHeading/behavior
FR9 SideNav.test.tsx 焦点环套件 整个标题链接、折叠链接、菜单触发器 缺少共享环类将失败。 audit:SideNavHeading/accessibility
FR10 SideNav.test.tsx SideNavHeading 菜单弹出窗口套件(触摸和鼠标滑动) 触摸和鼠标在项目之间滑动;一个调用按钮和链接;在外部释放 移除该采用机制会使滑动测试失败。 —
FR11 SideNav.test.tsx SideNavHeading 用例:“在没有 href 的情况下将可见标题包含在菜单触发器名称中”、“在翻译后的菜单触发器名称中包含标题”(韩语目录),以及“在提供菜单和 href 时将 chevron 渲染为单独触发器” 整个触发器;链接加触发器;翻译后的区域设置 没有标题的名称,或丢弃该标题的翻译名称,将失败。 audit:SideNavHeading/accessibility
RTL 关系 RTL 审计在 SideNav / Default 上精选了 D2 和 D8 目标(apps/storybook/rtl-audit/targets.json) 标题图标和标题,具有 0px 起始内边距和 8px 结束内边距;LTR 和 RTL 如果图标不在标题的内联起始位置,或者结束内边距在 RTL 中停留在同一物理侧,则视为不符合 D2 或 D8。 audit:SideNavHeading/i18n-rtl

以下内容从源码读取,暂无针对性测试:

  • FR1:转发的 ref、side-nav-heading 目标、各部分顺序以及单行截断。
  • FR2:在 links-plus-trigger 配置中,块的其余部分打开菜单。
  • FR3:图标和菜单配置标题链接上的 as,以及其他行的 Link 组件。
  • FR5:点击防护、Escape 和焦点返回。其首次打开的延迟是一个实现缺口。
  • FR6:popover 的位置和菜单的名称。
  • FR7;FR8 的 tooltip 在内联结束处的位置;以及 FR9 对 popover 的标题按钮和链接图标的要求。

决策日志

未记录任何组件局部决策。

未决问题

无。

内容边界

本文件不重复使用者的 prop 表格、示例或 popover 机制,而是链接到各自的所有者。

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