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-groupsFR5 赋予它的按压跟踪之外,它不会添加任何全局监听器。
无障碍契约¶
- AR1 — 组名。 组暴露
role="group",并将其label作为可访问名称;成员保留各自的名称(family:buttonsFR11)。 - AR2 — 键盘。 FR8–FR10 即键盘契约。
- AR3 — 禁用状态暴露。 被禁用的组在组上暴露
aria-disabled;成员按照component:ButtonAR5 暴露禁用状态。 - 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-085FR7 适用于组禁用。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| 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