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-apiINV8 要求 ref 到达契约所承诺的元素。 - 方向键打开行是建议性的。 共享的菜单按钮绑定将 AR1 的 ArrowDown 和 ArrowUp 打开行按建议性要求执行,因此未命中第一行或最后一行的键盘打开不会使任一绑定通道失败。
spec:AST-020FR9 将已采纳的期望变为必需要求。
所有权边界¶
拥有
- 溢出菜单的组合及其可见的纯图标触发器默认值。
- 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-020FR15),因为它们是已发布的功能而保留。指针打开会将焦点放在菜单容器上,随后的第一次 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