跳转至

MoreMenu 组件契约

契约概览

区域 契约
公开契约 MoreMenu,包含 items、label(默认"More options")、variant(ghost)、size(周围的尺寸上下文,否则为 md)、icon、isDisabled、placement、alignment、presentation、isMenuOpen 和 onOpenChange;目标为 more-menu。
行为 一个带有工具提示的纯图标溢出 Button,用于打开包含 items 的 DropdownMenu;MoreMenu 将打开状态、placement、alignment 和 presentation 转发给 DropdownMenu,并且自身不添加任何菜单运行时。
终端用户影响 用户可以在一个名为"More options"的按钮后面找到次要操作;键盘用户可以将其作为 APG 菜单按钮打开。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无公开变更。存在两个实现差距(见当前状态影响)。
审查检查项 拒绝将 more-menu 移到触发器上,拒绝并行的菜单运行时,拒绝失去其名称、aria-haspopup、aria-expanded 或 aria-controls 的触发器。
管理规则 spec:AST-020(模式绑定);architecture:component-theming-surface;architecture:layer-runtime;family:overlay-dismissal。

此表是审查概览;以下正文具有权威性。

意图

MoreMenu 提供一个可见的纯图标溢出触发器,并将其操作呈现委托给 DropdownMenu。它拥有触发器的默认值、组合面板上的 more-menu 目标,以及它转发给 DropdownMenu 的内容。消费者用法位于 MoreMenu.doc.mjs 中。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;运行时、DOM、样式、目标和公开 API 均保持不变
  • 受控/非受控行为:isMenuOpen 和 onOpenChange 原样传递给 DropdownMenu
  • 迁移决策:无

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

当前状态影响

  • bottom-sheet 触发器会丢失 ref。 在 presentation="bottom-sheet" 或紧凑触屏上的 presentation="adaptive" 情况下,DropdownMenu 会替换 MoreMenu 传递给触发器的 ref,因此调用方的 ref 会一直为空。architecture:public-component-api INV8 要求 ref 到达契约所承诺的元素。
  • 方向键打开行是建议性的。 共享的菜单按钮绑定将 AR1 的 ArrowDown 和 ArrowUp 打开行按建议性要求执行,因此未命中第一行或最后一行的键盘打开不会使任一绑定通道失败。spec:AST-020 FR9 将已采纳的期望变为必需要求。

所有权边界

拥有

  • 溢出菜单的组合及其可见的纯图标触发器默认值。
  • Menu 表面当前的 more-menu 目标,它是组合后的 DropdownMenu 面板上的第二个类。

不拥有 / 非目标

  • 触发器按钮的呈现——委托给 component:Button。
  • 默认语义触发器图形的解析——委托给 Icon 注册表;当前图形直接渲染在 Button 内部,不携带 Icon 的 icon 目标。任意由调用方渲染的触发器内容仍归调用方所有。
  • 菜单面板的生命周期和呈现切换——由 DropdownMenu 拥有,此处不纳入契约。
  • 锚定的操作行、分区、分隔线、可选中指示器和嵌套弹出层——由 DropdownMenu 拥有,此处不纳入契约。
  • BottomSheet 的操作行和列表——通过 DropdownMenu 委托给 component:List;触控框架仍由 component:BottomSheet 拥有。
  • 共享层的生命周期或关闭策略。

公开概念

没有组件本地概念。操作数据和呈现值属于 DropdownMenu;消费者 props 在 MoreMenu.doc.mjs 中有文档说明。

行为与布局契约

ID 不变量 依据
FR1 每次渲染都包含一个仅图标的 Trigger 按钮。锚定呈现还会渲染一个 DropdownMenu 所拥有的 Menu 表面;BottomSheet 呈现仅在工作表打开时渲染其 Menu 表面。锚定呈现使用 Pointer 操作行;BottomSheet 呈现使用 Touch 操作行。默认触发器图标是当前活动注册表中的 moreHorizontal 图形;icon 可用任意 React 内容替换它。 当前源码、文档和测试
FR2 more-menu 目标作为额外类应用于组合后的 DropdownMenu 面板,位于任何调用方 className 之前。它不应用于 Trigger 按钮。 当前源码、文档和测试
FR3 Button 拥有 Trigger 按钮,Icon 注册表负责默认语义触发器图形的解析。DropdownMenu 拥有 Pointer 操作行,包括键盘如何到达禁用行(DropdownMenu FR17);List 拥有通过 DropdownMenu 的 BottomSheet 路径渲染的 Touch 操作行。 当前源码和所有者文档
FR4 MoreMenu 将 open 状态、placement、alignment、presentation、xstyle、style 和 data-testid 转发给 DropdownMenu,而不添加并行的菜单运行时,并且不显示 chevron。其默认位置与 DropdownMenu 一致。宿主 data-* 属性到达触发器按钮而非菜单;按钮的 name、id 和 disclosure 属性保持组件拥有。 当前源码和测试
FR5 触发器由 label 命名(否则使用已翻译的 @astryx.moreMenu.label,即“More options”),将该名称显示为工具提示,使用 variant(默认 ghost)和 size(默认来自周围尺寸上下文,否则为 md),在锚定呈现中将 ref 转发到触发器,并遵循 isDisabled:禁用的触发器不会因任何按键或按压而打开。 当前源码和测试

允许的变化

  • AV1 — Trigger 图标。 默认的语义化三点图标可被图标组件或任意 React 内容替换,而不会将 MoreMenu 目标移到触发器上。
  • AV2 — 呈现。 DropdownMenu 可以解析当前的锚定或 BottomSheet 呈现,而 MoreMenu 保持相同的触发器和 Menu 表面所有权。
  • AV3 — 内部。 操作行、分区、分隔线、图标、可选择指示器和嵌套操作可根据 DropdownMenu 的当前数据契约变化。

代表性状态

状态 必需不变量 允许的变化
默认溢出菜单 Trigger 按钮使用默认的 Icon 解析字形,Menu 表面带有 more-menu。 按钮的 size、variant、placement 和 alignment 可以变化。
任意图标内容 Trigger 按钮仍由 Button 拥有,而调用方内容绕过 Icon 所有权。 调用方拥有渲染的内容。
Pointer 呈现 DropdownMenu 拥有锚定的 Menu 内部和 Pointer 操作行。 行、分区、分隔线和嵌套 flyout 可以变化。
Touch 呈现 DropdownMenu 拥有由 BottomSheet 支持的 Menu 内部;List 拥有 Touch 操作行。 Touch 行和钻取深度可以变化。

转换与优先级顺序

  • ORD1 — Trigger 图标。 先是 icon,然后是注册表中的 moreHorizontal。
  • ORD2 — 尺寸。 先是 size,然后是周围尺寸上下文,最后是 md。

性能与资源

  • 无资源规则;MoreMenu 不会自行添加监听器或测量。

无障碍契约

  • AR1 — 锚定的触发器是 Menu Button。 在锚定的 Pointer 呈现中,MoreMenu 的仅图标触发器满足 APG Menu Button 模式所要求的部分:button 角色、以其标签作为名称、aria-haspopup="menu"、aria-expanded、aria-controls,以及 Enter 或 Space 打开并将焦点置于第一个启用的行。ArrowDown 在第一个启用行打开、ArrowUp 在最后一个启用行打开,这超出了该模式的必需集合,是一个具名异常(spec:AST-020 FR15),因为它们是已发布的功能而保留。指针打开会将焦点放在菜单容器上,随后的第一次 ArrowDown 会移动到第一行。在 BottomSheet 呈现中,触发器打开一个对话框并声明 aria-haspopup="dialog",这不在该模式范围内。

设计关系

结构或状态 设计要求 表示来源 层级角色 组件契约
触发器按钮 提供次要操作的可见且可发现的入口。 component:Button 辅助 FR1, FR3
图标解析的触发器图标 从当前 Icon 注册表绘制语义化的三点图形。 Icon 注册表 辅助 FR1, FR3
调用方渲染的触发器内容 呈现通过图标覆盖提供的任意调用方内容。 调用方提供的内容 依上下文而定 FR1, FR3
菜单表面 将 MoreMenu 的目标添加到组合后的 DropdownMenu 面板,而非触发器。 当前源码与公开文档 主要 FR1, FR2
指针操作行 在锚定呈现中展示操作或嵌套浮出触发器。 DropdownMenu 主要 FR1, FR3, FR4
触控操作行 在触控呈现中通过 ListItem 展示操作或钻取条目。 component:List 主要 FR1, FR3, FR4

菜单表面即 DropdownMenu 面板本身。它同时承载 astryx-more-menu 和 DropdownMenu 自身的面板目标;该局部类并非包装器,也不会重新指向触发器。DropdownMenu 仍然是呈现运行时与锚定内部的属主。其触控路径将操作行委托给 List,而非将指针行目标扩展到 BottomSheet 呈现中。

主题化结构

{
  "Trigger button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Icon-resolved trigger icon": {
    "none": {
      "reason": "unsettled: The current useIcon artwork renders directly inside Button; whether it should carry Icon's icon target needs an owner decision."
    }
  },
  "Caller-rendered trigger content": {
    "none": {
      "reason": "intentional: Arbitrary React icon content is caller-owned and receives no MoreMenu target."
    }
  },
  "Menu surface": {"target": "more-menu"},
  "Pointer action row": {
    "delegatesTo": {
      "owner": "component:DropdownMenu",
      "target": "dropdown-menu-item"
    }
  },
  "Touch action row": {
    "delegatesTo": {"owner": "component:List", "target": "list-item"}
  }
}

家族与系统关系

  • architecture:component-theming-surface 拥有结构归属判定、局部菜单表面目标以及组合委托规则。
  • architecture:icon-resolution-and-component-slots 拥有活动主题图标解析。MoreMenu 的默认图形使用该注册表,但目前绕过了 Icon 绘制的 icon 目标。
  • architecture:interaction-modality 拥有通过 DropdownMenu 继承的共享指针、触控、键盘与自适应呈现边界。
  • architecture:layer-runtime 拥有当前 DropdownMenu Popover 宿主、原生轻触关闭协调与 BottomSheet 宿主区分。MoreMenu 不添加并行的层运行时。
  • family:overlay-dismissal 拥有共享的 Escape 与平台关闭顺序,并通过其组合的 DropdownMenu 根节点将 MoreMenu 记录为共享属主;BottomSheet 呈现保留了 BottomSheet 已记录的仅本地采用缺口。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, FR4 MoreMenu.test.tsx 渲染、指针、BottomSheet 与定位测试套件,及其对“将 data-* 属性传递给触发器按钮而非菜单”和“将 data-* 属性传递给 BottomSheet 触发器而非面板”的用例 默认、自定义图标、指针、触控 替换组合或更改转发行为会导致现有渲染/交互测试失败。 audit:MoreMenu/anatomy
FR2 MoreMenu 目标测试、源码检查与主题化目标清单 已关闭的触发器与组合后的菜单面板 将 more-menu 移到触发器上或将其从面板中移除,会导致目标证据失败。 audit:MoreMenu/theming
FR3 MoreMenu、DropdownMenu、Button、Icon 和 List 的源/所有者测试 Trigger、图标分支、指针行、触摸行 某个组合部件失去其所有者目标,或被记录为 MoreMenu 所有的新后代。 audit:MoreMenu/theming
FR5 MoreMenu.test.tsx 的 label、自定义标签、ref、禁用按键以及禁用时保持关闭的测试 默认和自定义标签;禁用状态 名称丢失,或禁用的触发器仍能打开,即为失败。 audit:MoreMenu/behavior
AR1 MoreMenu.test.tsx 的 label、弹层和指针聚焦测试;菜单按钮模式绑定的 MenuButton.a11y.test.tsx 和 MenuButton.a11y.chromium.spec.ts(它们渲染 MoreMenu 的状态);DropdownMenu.test.tsx 中共享 Button 触发器路径上的 ArrowDown 和 ArrowUp 触发键测试 默认和自定义图标触发器;关闭/打开;Enter、Space、ArrowDown、ArrowUp Trigger 失去其 label、aria-haspopup="menu"、aria-expanded 或 aria-controls,或者按 Enter 或 Space 打开后未落在第一个启用行上。 audit:MoreMenu/accessibility
层级关系 MoreMenu.test.tsx、DropdownMenu.test.tsx 以及当前的层级/关闭记录 Light dismiss(点击外部关闭)、Escape、指针、触摸 文档赋予 MoreMenu 一个并行的运行时,或错误陈述了当前的关闭所有者。 audit:MoreMenu/behavior
主题 anatomy 映射 scripts/check-knowledge.mjs 规范 anatomy 和当前目标 缺失、多余、带前缀、过期或未分类的映射会导致仓库验证失败。 audit:MoreMenu/theming
RTL 关系 RTL 审计精选的 D4 目标(apps/storybook/rtl-audit/targets.json),针对 MoreMenu / Default(菜单已打开) 打开的菜单与其 Trigger 相对;LTR 和 RTL 在 RTL 中未移动到其 Trigger 镜像侧的菜单无法通过 D4。 audit:MoreMenu/i18n-rtl

从源码中读取,尚无针对性测试:

  • FR1:注册表中的 moreHorizontal 用作默认的触发器图标。
  • FR2:more-menu 位于调用方 className 之前,且 Trigger 按钮上不含 more-menu。
  • FR4:转发 isMenuOpen、onOpenChange、xstyle 和 style,且没有 chevron 图标。
  • FR5:tooltip、ghost 默认值、由周围尺寸上下文提供的尺寸、md 默认值,以及 ref 到达 Trigger 按钮。
  • AR1:bottom-sheet 呈现中的 aria-haspopup="dialog"。

决策日志

未记录任何组件本地决策。

未决问题

  • OQ1 —— 默认的触发器图形是否应通过 Icon 的公共目标渲染?(human-api)当前的注册表查找保留了语义化图形替换,但将绘制的字形留在了 icon 目标之外。

内容边界

本文件不重复消费者 props 表、DropdownMenu 条目示例、图标解析规则、实现步骤,以及共享的模态、层级、关闭和主题规则。它链接到这些内容的所有者。

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