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