跳转至

DropdownMenuGroup 组件契约

契约概览

领域 契约
公共契约 一组复合模式的行,具有可选的 title、children、根级输入和 ref。
行为 渲染一个由可见标题命名的 role="group";该标题是纯文本,漫游焦点和 typeahead 会跳过它。无标题的组是未命名组,除非调用方为其命名。
最终用户影响 屏幕阅读器用户会像有视力用户看到的那样,将带标题的行簇听为一个已命名组;方向键跨组边界移动时,就像这些行是平铺的一样。
构建者影响 构建者使用与数据模式 section 相同的标题外观,为复合行添加标题。
兼容性/就绪度 记录已发布行为;无 API、默认值或 DOM 变更。
评审检查 拒绝下列情况:标题变成菜单项或焦点停留点;有标题的组未被其标题命名;丢失 section-heading 目标。
管理规则 component:DropdownMenu/DEC-6;architecture:public-component-api;architecture:component-theming-surface。

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

意图

DropdownMenuGroup 为复合模式菜单提供了数据模式 {type: 'section'} 条目已经具备的标题分组(component:DropdownMenu/DEC-6)。

兼容性与迁移

  • 已发布默认值保留:是。
  • 兼容性类别:记录已发布行为;无公共 prop、默认值、导出或 DOM 变更。
  • 受控/不受控行为:不适用。
  • 迁移决策:无。

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

所有权边界

拥有

  • 一个 role="group" 根,其名称来自标题,以及标题本身,带有 dropdown-menu-section-heading 目标。
  • 根的组成:ref、宿主属性和处理程序。

不拥有 / 非目标

  • 漫游焦点和 typeahead —— 由 component:DropdownMenu 拥有。
  • 内部的行 —— 由每个行组件拥有。
  • 标题内部的可聚焦内容:方向键无法到达。

公共概念

概念 封闭值或状态 含义 可用性 默认值 所有者 稳定性 无效值行为
标题 不存在;任意 React 节点 一个为组命名的可见标题。 复合模式 不存在 组件 稳定 不存在时不渲染标题,也没有自身的名称。

行为与布局契约

ID 不变量 依据
FR1 当存在 title 时,该组是一个 role="group",其 aria-labelledby 指向其可见标题;该标题带有 dropdown-menu-section-heading,是纯文本而非菜单项,并且漫游焦点和 typeahead 会跳过它。 component:DropdownMenu 的 DEC-6;当前测试
FR2 当没有 title 时,该组是未命名的 role="group",或采用调用方提供的名称。 当前测试
FR3 方向键可以跨组边界移动,就像这些行是平铺的一样;标题内部的可聚焦节点无法通过方向键到达。 当前测试
FR4 ref、宿主属性和处理程序都会传递到该组元素上,同时它保留自己的 role 和标题名称。 architecture:public-component-api;当前测试

允许的变化

  • AV1 — 标题内容。 标题可以是任意 React 节点。

代表性状态

状态 必需不变量 允许的变化
有标题 由其标题命名。 标题内容。
无标题 未命名,或由调用方命名。 —

转换与优先级顺序

  • ORD1 — 名称。 标题 → 调用方名称 → 无。

性能与资源

  • PR1 — 仅渲染。 该组不拥有任何状态、效果、监听器或观察器。

无障碍契约

  • AR1 — 命名组。 有标题的组会以其标题文本进行播报;该标题不是菜单项。

设计关系

结构或状态 设计需求 表示权威 层级角色 组件契约
标题 为一组行提供标签,类似 data-mode 的区块标题。 component:DropdownMenu 支持性 FR1

component:DropdownMenu 将 dropdown-menu-section-heading 目标映射到其主题结构,因此本记录不携带结构-主题映射。

家族与系统关系

  • component:DropdownMenu 拥有键盘模型和区块标题目标映射。
  • architecture:public-component-api 拥有根组合。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
FR1, AR1, ORD1 DropdownMenu.test.tsx 的 DropdownMenuGroup 用例("renders a role=\"group\" named by its heading"、"renders the heading with the data-mode theme class"、"the heading is not a menuitem and roving focus skips it"、"typeahead never lands on the heading") 标题组 若一个组未被其标题命名、缺少标题目标,或标题获得焦点或被 typeahead 匹配,则失败。 audit:DropdownMenuGroup/semantics
FR2 DropdownMenu.test.tsx 中的 "an untitled group is an unnamed role=\"group\"" 以及 "an untitled group takes a caller-supplied accessible name" 无标题(有/无调用者提供的名称) 若为无标题组发明名称,或丢失调用者提供的名称,则失败。 audit:DropdownMenuGroup/semantics
FR3 DropdownMenu.test.tsx 中的 "arrow navigation steps across a group boundary as if the rows were flat" 以及 "a focusable node in the heading is not reachable by the arrow keys" 两个组;标题中有可聚焦内容 若在边界处停止,或箭头键可到达标题中的可聚焦节点,则失败。 audit:DropdownMenuGroup/accessibility
FR4 DropdownMenu.test.tsx 中的 "forwards a ref to the group element" 以及 "forwards host attributes to the group while keeping its role and heading name" Ref;宿主属性 若 ref 或属性丢失,或角色或名称被替换,则失败。 audit:DropdownMenuGroup/api
PR1 证据缺口:没有任何测试断言生命周期资源不存在 — — audit:DropdownMenuGroup/behavior

决策日志

无组件本地决策;component:DropdownMenu/DEC-6 决定该组件。

开放问题

无。

内容边界

本文件不重复使用者 prop 表格/示例、当前审计结果、实施步骤或父契约。它链接到这些内容的拥有者。

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