跳转至

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