跳转至

ButtonGroup 组件契约

契约概览

领域 契约
公共契约 无变更。ButtonGroup 接受 label、orientation、size、elevation、isDisabled,以及 Button 或 IconButton 子组件。
行为 一个带标签的 role="group",将其 Button 成员连接成一个整体表面,为它们提供默认尺寸和自身的禁用状态,拥有一个共享海拔,并作为一个 Tab 停靠点支持方向键漫游。
最终用户影响 键盘用户只需一次 Tab 即可到达整个组,并通过方向键在其中移动。禁用的组保留其唯一的 Tab 停靠点,因此键盘用户可以找到它并听到其处于禁用状态。
构建者影响 无。
兼容性/就绪状态 无 API 或默认值变更。Tab 停靠点会跳过已禁用和仅忙碌的成员,换行的成员会失去连接几何形状;两者均列在“当前状态影响”下。
审查检查 拒绝没有名称的组、成员之间的间隙、圆角内角、成员上的阴影、超过一个 Tab 停靠点,或方向键从成员已打开的菜单中窃取按键。
约束规则 family:buttons FR3, FR8, FR10–FR12, AV5; architecture:component-size-cascade INV3–INV8; spec:AST-085 FR1, FR7; spec:AST-038 FR7, FR8。

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

意图

ButtonGroup 将几个相关操作呈现为一个相连的控件。它拥有组的可访问名称、连接几何形状、共享海拔、继承的尺寸和禁用状态,以及组的单 Tab 停靠点键盘模型,如 family:buttons 所规定。消费者用法见 ButtonGroup.doc.mjs。

兼容性与迁移

  • 已发布默认值保持不变:鼠标场景为 yes;在触摸呈现下,按下会获得跨按钮的滑动;orientation="horizontal"、size="md"、elevation="none"、isDisabled={false}
  • 兼容性类别:无公共属性、默认值或导出变更;在触摸呈现下,DOM 会在每个被跟踪的按钮上新增 action-group 项目标记,在组根节点上新增手势宿主的 data-astryx-touch-action 标记以及命中层的 inset 属性;启用状态的组根节点还是 position: relative,因此绝对定位的后代在该处可相对于它解析
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 组根节点:role、可访问名称、方向和禁用状态暴露,以及 button-group 目标。
  • 其 Button 成员绘制的连接几何形状:仅外角圆角、前缘分隔线,且无按下缩放。
  • 一个共享的静止海拔,以及扁平的成员。
  • 它赋予其成员的默认尺寸和禁用状态。
  • 漫游焦点:一个 Tab 停靠点、方向键、Home 和 End。

不拥有 / 非目标

  • 每个成员自身的表面、命名、激活、待定和禁用渲染——由 component:Button 和 component:IconButton 拥有。跨成员滑动的按下作用于被抬起的成员,此行为由 family:action-groups 拥有。
  • 成员的菜单或其他层,以及在其内部按下的按键——由该成员拥有(例如 component:DropdownMenu)。
  • 跨切换的选择状态——由 component:ToggleButtonGroup 拥有。
  • 水平溢出——未约定;该组不换行也不折叠。
  • 嵌套 ButtonGroups——不受支持;行为未约定。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Orientation horizontal, vertical 行和方向键的方向。 始终。 horizontal component:ButtonGroup 稳定 TypeScript 拒绝其他值。
Size sm, md, lg 成员的默认尺寸。 始终;成员自身的 size 优先。 继承的尺寸,否则为 md family:buttons 稳定 TypeScript 拒绝其他值。
Elevation none, low, med, high 整个连接表面下方的阴影。 始终;成员不绘制阴影。 none family:buttons 稳定 TypeScript 拒绝其他值。
Disabled off, on 每个 Button 成员都会被禁用。 始终。 off component:ButtonGroup 稳定 不适用。

行为与布局契约

ID 不变式 依据
---- ---- ----
FR1 根元素是单个元素,具有 role="group",并且 aria-label 设置为 label。它通过 data-orientation 反映方向,绝不使用 aria-orientation,并且仅在禁用时设置 aria-disabled="true"。ref、data-testid、className、style、xstyle 以及其他 DOM 属性都会传递到它。 family:buttons FR11;当前源代码和测试
FR2 成员彼此紧贴、没有间隙,并沿交叉轴拉伸:水平时排列成行,垂直时排列成列。 family:buttons FR12;当前源代码
FR3 组几何由 Astryx Button 成员绘制;其他子元素保留自己的绘制。只有组的外侧角是圆角:第一个成员的起始角,以及最后一个成员的末尾角。一个成员在自身之后渲染的尾部层元素(popover、template 或 dialog)不计为成员,因此真正的最后一个成员保留其圆角。任何其他后续元素(包括 display-contents 包装器或原生 button)都计为成员。包裹在 Tooltip 或 HoverCard 中的 Button 成员 MUST 像直接成员一样加入连接表面(family:buttons FR12)。实现差距:在 display-contents 包装器内部,Button 同时是第一个和最后一个子元素,因此在包含两个或更多成员的组中,无论它位于何处,它都会保持所有四个角为圆角;并且当它不是第一个时,不会绘制分隔线。 family:buttons FR12;当前测试
FR4 第一个之后的每个 Button 成员都会在其起始边缘(水平时为 inline-start,垂直时为 block-start)绘制一条分隔线,使用边框颜色;或者在 primary 或 destructive 成员上使用 on-accent 颜色;被包裹的成员不会绘制(FR3 差距)。成员不采用 Button 的按下缩放。 family:buttons FR12;当前源代码
FR5 该组根据元素圆角为其 elevation 绘制阴影。每个 Button 成员都不绘制阴影,并反映 data-elevation="none",无论其自身的 elevation 如何声明。 family:buttons FR8、FR10;当前测试
FR6 该组将其解析后的尺寸提供给直至下一层边界(spec:AST-038 FR7、FR8)的后代元素:先是显式的 size,然后是最近的外部提供者,再然后是 md。成员自身的 size 优先。 architecture:component-size-cascade INV3–INV8;当前源码;spec:AST-038 FR7
FR7 在禁用状态下,每个 Button 成员 MUST 按照 component:Button FR10 被禁用:可通过 aria-disabled 聚焦、处于 inert 状态,且绝不执行其动作,从而使组保持其 Tab 停留点(spec:AST-085 FR1、FR7)。 family:buttons FR3;spec:AST-085 FR7;当前测试
FR8 该组是一个 Tab 停留点。停留点从第一个启用的成员开始,并随箭头导航移动。链接成员也计为成员。停留点 MUST 始终恰好位于一个成员上,而变为忙碌或禁用的成员 MUST 保持该停留点(component:Button FR9、FR10;spec:AST-085 FR1、FR7)。实现差距:该组仅在自己的渲染之后以及焦点进入成员时修复停留点,且每次修复要么保留一个已启用的持有者,要么将停留点交给第一个启用的成员。在两次修复之间,停留点可能落在已变为仅忙碌、已禁用或已卸载的成员上,因此该组可能出现第二个停留点或没有停留点;通过指针或代码进入的焦点不会占据停留点,因此下一次 Tab 或 Shift+Tab 可能会停在组内。 family:buttons AV5;WAI-ARIA APG roving tabindex;当前测试
FR9 水平组使用 Left 和 Right 键按视觉顺序移动,在 RTL 下方向相反;垂直组使用 Up 和 Down 键移动。Home 和 End 跳转到第一个和最后一个启用的成员。移动在两端循环。 family:buttons AV5;当前测试
FR10 在成员已打开的层(如 DropdownMenu)内按下的按键属于该层,并且组在其自身成员上保留 Tab 停留点。位于弹出层或其他层中的组仍自行处理其方向键。组的上下文不会触及在成员层内渲染的 Button(spec:AST-038 FR7)。 当前源代码和测试;spec:AST-038 FR7
FR11 根元素带有 astryx-button-group,并反映 data-size、data-orientation 和 data-elevation。 family:buttons FR10;architecture:component-theming-surface;测试

允许的变体

  • AV1 — 成员。 Button、IconButton 以及由 Button 触发的 DropdownMenu 是受支持的成员;各成员的变体可以不同。
  • AV2 — 主题绘制。 主题可以通过 button-group 和 button 重新设置组和成员表面的样式,而不改变相连的几何结构。

代表性状态

状态 必需不变量 允许的变体
水平,静止 具名组;第一个成员上只有一个 Tab 停留点;仅外角。 成员变体。
垂直 列式布局;按 Up 和 Down 方向键移动焦点;块首分隔线。 —
抬升 组上有阴影;成员为平面。 层级。
尾部 DropdownMenu 菜单触发器保持尾部圆角;打开菜单内的方向键仍归属于该菜单。 菜单内容。
单个成员禁用 实现差距:当组修复 Tab 停留点时(FR8),Tab 停留点会离开该成员。 是否显示 Tooltip。
组禁用 组上设置 aria-disabled;每个成员可聚焦且为 inert;一个 Tab 停留点。 —

变换与优先级顺序

  • ORD1 — 成员尺寸。 先应用成员的 size,再应用组的解析尺寸。
  • ORD2 — 成员抬升。 在组内,始终为 none;由组的 elevation 负责绘制。
  • ORD3 — 成员可用性。 当组或成员被禁用时,该成员即被禁用;任何一方都无法重新启用另一方。否则,应用 Button 自身的可用性规则。

性能与资源

  • PR1 — Tab 停留点修复。 组在自身每次渲染后以及焦点进入某个成员时修复 Tab 停留点;除了 family:action-groups FR5 赋予它的按压跟踪之外,它不会添加任何全局监听器。

无障碍契约

  • AR1 — 组名。 组暴露 role="group",并将其 label 作为可访问名称;成员保留各自的名称(family:buttons FR11)。
  • AR2 — 键盘。 FR8–FR10 即键盘契约。
  • AR3 — 禁用状态暴露。 被禁用的组在组上暴露 aria-disabled;成员按照 component:Button AR5 暴露禁用状态。
  • AR4 — 焦点指示器。 每个成员绘制 Button 的焦点指示器。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
Button 成员连接成单一表面,且仅外侧有圆角。 当前源码和测试 突出 FR2, FR3
Divider 成员之间的细前缘边框;在实色成员上使用 on-accent。 当前源码 辅助 FR4
组阴影 连接表面下方的单个阴影。 当前源码和测试 辅助 FR5

没有任何设计记录约束 ButtonGroup。根元素承载 button-group 目标;Button 和 Divider 的结构部件由每个成员的 button 目标绘制。使用方结构未命名根部件,因此该记录没有结构主题映射。

家族与系统关系

  • family:buttons 为 ButtonGroup 指定连接几何、漫游焦点、继承尺寸和禁用状态,以及一个共享的阴影层级(FR8、FR11、FR12);ButtonGroup 采用它们。
  • component:Button 根据组的上下文绘制连接几何,并负责每个成员的行为。
  • architecture:component-size-cascade 负责尺寸继承(FR6)。
  • spec:AST-085 FR7 适用于组禁用。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
FR1, AR1 ButtonGroup.test.tsx 验证角色、标签、ref、data-testid、方向 水平和垂直 缺少名称、aria-orientation、丢失的 ref 或丢失的 data-testid 将导致失败。证据缺口:没有测试传递 className、style 或 xstyle。 audit:ButtonGroup/accessibility
FR3 Chromium 交互通道中的 ButtonGroupCorners.interaction.browser.spec.ts;ButtonGroup.test.tsx 尾端圆角套件(编译后的选择器形状和成员关系;jsdom 永不接收该规则) 两个成员,水平和垂直;popover、template 和 dialog 片段位于成员之后,最多七个;位于 popover 之间的成员;display-contents 包装器、Tooltip 包裹的和原始 button 跟随者;带有 tooltip 的 DropdownMenu 尾随成员;InputGroup 按钮 addon 位于最后和最先 方形尾随成员或圆形内侧成员失败;使用 :last-child 或兄弟相对 :has() 的编译后尾随选择器失败。证据缺口:jsdom 套件和浏览器 story 仅渲染位于最后位置的包裹成员并检查其前面的成员;没有测试检查任何位置下包裹成员自身的圆角或分隔线。 audit:ButtonGroup/layout
FR5, FR11 ButtonGroup.test.tsx 阴影层级套件 每一层级;成员带有自身的阴影层级 两个层级使用相同的类、data-elevation 不匹配,或成员未报告 none 则失败。 audit:ButtonGroup/theming
FR11(目标、尺寸) 证据缺口:没有测试断言根元素上的 astryx-button-group 或 data-size 每种尺寸 — audit:ButtonGroup/theming
FR7、AR3 ButtonGroup.test.tsx 禁用相关用例 组禁用 如果存在可操作成员、原生 disabled 成员,或没有单一 Tab 焦点位置的禁用组,则失败。 audit:ButtonGroup/accessibility
FR8、AR2 ButtonGroup.test.tsx roving-tabindex 测试套件 进入和离开;禁用成员;卸载;变为禁用;链接 如果出现两个 Tab 焦点位置或丢失焦点位置,则失败。当仍有启用成员时,该套件断言禁用成员不会持有焦点位置,并且焦点位置会被修复到远离该禁用成员的位置,与 FR8 缺口一致;当每个成员都被禁用时,焦点位置停留在其中一个禁用成员上(“当每个成员都被单独禁用时,它保持其单一 Tab 焦点位置”)。证据缺口:没有测试忙碌或自我卸载的持有者、指针焦点,或挂载后变为禁用的组。 audit:ButtonGroup/accessibility
FR9、FR10、AR2 ButtonGroup.test.tsx 键盘导航测试套件;useListFocus.test.tsx 中的“useListFocus disabled-item skipping”用于 Home 和 End(它们会到达启用的末端);layerScopedContext.test.tsx 中的“ends group-owned disabled state while preserving explicit and inner-group state”用于层边界 方向键、Home、End、垂直、RTL、打开菜单、位于弹出层内的组 方向错误、不换行、Home 或 End 落在禁用成员上、窃取菜单按键,或组状态泄漏到成员层中,均失败。 audit:ButtonGroup/accessibility
FR2, FR3, FR4, FR6 证据缺口:没有断言无间隙布局、分隔线绘制、缺失的按压缩放、非 Button 子项保留自身绘制,或成员尺寸继承超出渲染范围 — — audit:ButtonGroup/layout
ORD2 ButtonGroup.test.tsx 高程测试套件 具有自身高程的成员 未报告 none 的成员将失败。 audit:ButtonGroup/theming
ORD1, ORD3, PR1, AR4 证据缺口:没有测试断言成员尺寸优先级、启用组内成员的 isDisabled、Tab 停靠点修复时机,或成员焦点指示器 — — audit:ButtonGroup/behavior

当前状态影响

  • Tab 停靠点 (FR8)。 当组修复 Tab 停靠点时,它会留下一个已禁用或仅忙碌的成员;在修复之间,组可能拥有第二个停靠点或没有停靠点,包括在指针点击某个成员之后,或当持有者卸载或禁用自身时,这违反了 spec:AST-085 的 FR1 和 FR7。
  • 被包裹的成员 (FR3, FR4)。 包裹在 Tooltip 或 HoverCard 中的 Button 在任何位置都保持四个圆角,并且当它不是第一个时没有分隔线,这违反了 family:buttons 的 FR12。

决策日志

没有组件级决策。ButtonGroup 应用 family:buttons。

未解决的问题

无。

内容边界

本文件不重复使用方的 prop 表格/示例、当前审计结果、实施步骤或家族/系统规则。它链接到这些内容的所有者。

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