DropdownMenuDivider 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | DropdownMenuDivider / DropdownMenuDividerProps,以及 ContextMenuDivider 和 BreadcrumbMenuDivider 别名及其 props;BaseProps<HTMLDivElement> 减去调用方拥有的 role 和 aria-orientation;一个根 ref。 |
| 行为 | 一个无标签的水平分隔符划分指针菜单行,且不参与箭头键顺序;数据和复合指针模式渲染相同的组件。 |
| 最终用户影响 | 指针菜单分区保持视觉分离,而不会添加焦点停留点或更改行操作。 |
| 构建者影响 | 没有新的调用方选择。宿主属性、处理程序和样式输入继续组合在分隔符上。 |
| 兼容性/就绪状态 | 记录已发布行为;无 API、默认值或 DOM 更改。 |
| 审查检查 | 拒绝可聚焦的分隔符、更改的 role/方向、指针数据/复合差异、丢弃的根输入或移出可见分隔符的目标。 |
| 治理规则 | architecture:public-component-api/INV1,INV5–INV9;architecture:component-theming-surface/INV3–INV6;spec:AST-020。 |
此表是审查投影;以下正文具有权威性。
意图¶
DropdownMenuDivider 提供指针菜单呈现中行分组之间的视觉和编程边界。它直接以 DropdownMenu 名称发布,并通过 ContextMenu 和 Breadcrumbs 别名提供。它拥有分隔符语义、菜单间距、根输入组合以及 dropdown-menu-divider 主题目标。外围的 DropdownMenu、ContextMenu 或 BreadcrumbItem 拥有菜单生命周期和行导航;Divider 提供基础分隔线几何形状和绘制。
使用者语法和示例应放在 DropdownMenuDivider.doc.mjs 中。
兼容性与迁移¶
- 已发布默认值保留:是 — 一个水平、无标签的分隔符。
- 兼容性类别:记录已发布行为;无公共 prop、默认值、导出或 DOM 更改。
- 受控/非受控行为:不适用。
- 迁移决策:无。
使用者迁移说明应放在使用者文档和发布说明中。
所有权边界¶
拥有
- 一个水平分隔符根及其公共 ref、DOM/数据/ARIA、class、style、事件和
xstyle组合。 - 菜单特定的块轴间距。
- 同一可见根上的
dropdown-menu-divider目标。 - 跨 DropdownMenu、ContextMenu 和面包屑菜单的分隔符行的指针菜单数据/复合渲染一致性。
不拥有 / 非目标
- 菜单打开状态、焦点进入、行激活或箭头键导航 — 由 DropdownMenu、ContextMenu、BreadcrumbItem 及其共享 hooks 拥有。
- 触摸和 bottom-sheet 数据分隔符 — 这些呈现直接渲染 Divider,并由其父菜单表面拥有。
- 基础分隔线规则几何形状和 token 绘制 — 委托给 Divider。
- 调用方编写的分组含义 — 由产品调用点拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 分隔符行 | 一个水平无标签分隔符 | 划分相邻的指针菜单行分组,而不成为行或焦点停留点。 | 数据和复合指针菜单模式 | 在编写处存在 | 组件 | 稳定 | role 和方向被排除在调用方 props 之外,并保持由组件拥有。 |
| 根表面 | ref;DOM/数据/ARIA;class/style/xstyle/events | 在保留组件语义的同时扩展分隔符根。 | 每个分隔符行 | 省略 | 公共组件 API | 稳定 | 接受的输入进行组合;role 和方向保持权威性。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 该组件渲染一条无标签的水平分隔线,并带有指针菜单特有的块间距。 | 已发布源码/文档与针对性测试 |
| FR2 | 根元素暴露 role="separator" 与 aria-orientation="horizontal",保持在菜单项集合和方向键顺序之外,且永不可聚焦。 |
spec:AST-020;当前测试 |
| FR3 | 在指针菜单呈现中,数据 API 里的 {type: "divider"} 与复合分隔线组件或别名渲染出相同的组件 DOM、间距、语义和目标。 |
已发布文档/源码;数据/复合对等测试 |
| FR4 | 可见根元素同时承载委派的 divider 目标和菜单特定的 dropdown-menu-divider 目标;菜单间距在调用方 xstyle 之前应用。 |
architecture:component-theming-surface;当前源码和测试 |
| FR5 | 被接受的 ref、DOM/数据/ARIA、class、style、事件和 xstyle 会到达或在分隔线根元素上组合,且不会替换组件自有的 role 或 orientation。 |
architecture:public-component-api INV5–INV8;当前测试 |
允许的变化¶
- AV1 — 主题绘制。 委派的 Divider 和菜单特定目标可以重新样式化其自有表面,而不改变分隔线语义或焦点行为。
- AV2 — 调用方根输入。 受支持的主机属性、处理函数和样式输入可以变化,而组件自有的 role 和 orientation 保持不变。
代表性状态¶
| 状态 | 必需不变项 | 允许的变化 |
|---|---|---|
| 指针数据模式分隔线 | 数据驱动行之间的一条水平分隔线。 | 相邻行内容和当前主题可能变化。 |
| 指针复合分隔线 | DOM 和行为与指针数据模式分隔线一致。 | 可提供主机属性和受支持的样式输入。 |
| 公共别名 | ContextMenuDivider 和 BreadcrumbMenuDivider 渲染此组件。 | 所属菜单拥有生命周期和导航。 |
| 触控数据分隔线 | 不在本组件范围内;父级表面直接渲染 Divider。 | 触控菜单布局遵循父级契约。 |
| RTL | 水平、全宽的分隔线保持方向中立。 | 周围文本和菜单对齐方式可能镜像。 |
| 窄视口 | 分隔线保持在菜单内部,且不产生水平溢出。 | 菜单宽度遵循其所有者。 |
转换与优先级顺序¶
- ORD1 — 根组合。 先应用菜单间距,再应用调用方
xstyle;将菜单特定目标类与调用方className组合;保留调用方style和主机属性;保持 role 和 orientation 由组件自有。
性能与资源¶
- PR1 — 无外部生命周期。 DropdownMenuDivider 不安装任何监听器、观察器、计时器、请求、状态机或 Effect。
无障碍契约¶
- AR1 — 分隔线语义。 根元素暴露一个水平分隔线,且没有交互角色或 Tab 停止点。
- AR2 — 导航排除。 菜单导航仅收集菜单项角色,因此 ArrowDown 和 ArrowUp 会跨过分隔线而不会聚焦到它。
设计关系¶
| 解剖结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 菜单分隔线 | 在视觉上分隔相邻的菜单行组,而不与行内容竞争。 | 当前源码和委派的 Divider 令牌;未添加组件本地视觉决策 | 支持性 | FR1–FR4 |
未记录组件本地的视觉决策。
系列与系统关系¶
architecture:public-component-api负责导出和根输入组合。architecture:component-theming-surface负责目标放置和组合目标的归属。architecture:component-test-sufficiency负责相应的、可观察的证据。- DropdownMenu 直接导出该实现。ContextMenu 和 Breadcrumbs 将其重新导出为
ContextMenuDivider和BreadcrumbMenuDivider,并带有匹配的 props 别名;它们的指针呈现保留相同的组件契约。 - 触控和 bottom-sheet 数据分隔线绕过此组件,并在父级菜单契约下直接委托给 Divider。
- Divider 提供基础分隔线实现。
验证映射¶
| 契约 | 验证 | 代表性状态 | 突变或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR2, AR1, AR2 | DropdownMenu.test.tsx 的分隔线与对等用例(“在项目之间渲染分隔线”、“从任一模式渲染相同的分隔线”、“在箭头键顺序中跳过复合分隔线”、“将宿主属性转发给复合分隔线,同时保留其角色”);ContextMenu.test.tsx 的分隔线用例;Breadcrumbs.test.tsx “通过 BreadcrumbMenuDivider 别名渲染分隔线及属性类型” |
数据与复合指针菜单;别名;箭头键遍历 | 缺少分隔线、角色改变、分隔线出现在箭头键顺序中,或别名丢失,均会导致失败。证据缺口:没有测试断言 aria-orientation 或菜单块间距。 |
audit:DropdownMenuDivider/semantics |
| FR3 | DropdownMenu.test.tsx “从任一模式渲染相同的分隔线” |
数据与复合 | 两种模式之间的 DOM 不同则失败。 | audit:DropdownMenuDivider/behavior |
| FR4, FR5 | DropdownMenu.test.tsx “在分隔线上组合完整的公共根表面”以及对等用例中的 dropdown-menu-divider 类名断言;themingTargets.test.ts |
Ref、class、style、xstyle、handler | 丢失 ref、class、style、xstyle 或 handler,或缺少 dropdown-menu-divider 目标,则失败。证据缺口:没有测试断言委派的 divider 目标,或菜单间距在调用方 xstyle 之前生效。 |
audit:DropdownMenuDivider/api |
| PR1 | 证据缺口:没有测试断言不存在生命周期资源 | — | — | audit:DropdownMenuDivider/behavior |
决策日志¶
没有组件级决策。
未决问题¶
无。
内容边界¶
本文件不重复消费者属性表/示例、当前审计分数、截图矩阵、实现步骤或系统规则,而是链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx