按钮家族契约¶
意图¶
无论一个动作是带标签的、纯图标的、持久的、独立的还是分组的,用户都应遇到一套连贯统一的按钮系统。成员共享相同的控件几何、可访问名称要求、交互反馈、异步动作模型和表面归属。每个成员仍保有自己的语义,分别对应瞬时动作、导航目标、持久按压状态或分组。
ToggleButton 呈现 Button 的高度状态,但目前无法选择该家族的静止高度轴。家族为 ToggleButton 接纳了这一轴。其透明的幽灵表面仍是一个已知的视觉问题:高度或许能提供浮动边界,而非不透明填充或轮廓;本契约不要求新的背景处理。
成员规则¶
当一个组件的主要公开目的是激活类按钮的动作、保留按钮的按压动作状态,或将上述控件组合成按钮专属组并保持其共享表面和交互契约时,它便属于该家族。
- 成员: Button、IconButton、ToggleButton、ButtonGroup 和 ToggleButtonGroup。
- 协作者: Spinner 提供进行中反馈;Tooltip 提供可见说明;LinkProvider 提供 Button 的导航渲染器;SizeContext 提供继承的控件尺寸;DropdownMenu 可能为 ButtonGroup 贡献按钮触发器。这些协作者不会成为 Button 家族成员。
- 排除项: Link 的主要目的是导航,而非按钮表面。Switch、CheckboxInput 和 RadioList 表示设置或表单值,而非按钮动作。SegmentedControl 和 TabList 在各自的选择/导航契约下切换视图或目标。仅将 Button 用作触发器或动作槽的组件保留其自身家族成员资格。
成员资格取决于公开职责,而非是否导入 Button 或渲染了 <button> 元素。
共享所有者¶
- Button 拥有公共动作表面:原生按钮语义、焦点与按压反馈、尺寸、视觉变体、加载呈现、链接模式和静止高度。
- IconButton 是 Button 的显式纯图标投影,继承该表面契约,而不创建另一个动作模型。
- ToggleButton 复用 Button 表面,并增加持久的受控按压状态、按压状态视觉和可中断的按压动作。
- ButtonGroup 拥有相连动作组的几何、漫游焦点、继承的尺寸与禁用状态,以及一个共享的连接高度。
- ToggleButtonGroup 拥有单选或多选状态,以及不同 ToggleButton 表面的布局。它不会仅仅因为对选择进行分组就变成连接的视觉表面。
- 共享基元保留各自的契约。Spinner、Tooltip、Icon、Link 和 DropdownMenu 的行为在组合进成员时不会变成 Button 专属。
规范概念¶
| 概念 | 值或状态 | 默认语义 | 稳定性 |
|---|---|---|---|
| 激活模型 | 瞬时动作、导航、持久按压 | Button 和 IconButton 激活一次;ToggleButton 表示保留的按压状态 | 已发布的区别 |
| 内容模式 | 可见标签、自定义可见内容、纯图标 | 每个控件都有必需的可访问 label;纯图标在视觉上隐藏它 |
已发布的家族规则 |
| 尺寸 | sm、md、lg |
md;显式成员尺寸优先于继承的组尺寸 |
已发布的家族轴 |
| 视觉状态 | 静止、悬停、焦点、激活、禁用、加载;适用时还有按压 | 各状态保留控件几何和可访问目的;按压反馈遵循 spec:AST-094 中 FR11 在手指下的控件特征,以及在鼠标或笔下的精细指针特征(未实现:鼠标按下仍绘制 :active) |
已发布的家族规则 |
| 异步动作 | 无、单次触发、可中断的持久动作 | 普通动作在等待期间去重;持久切换保持可逆 | 已发布的区别 |
| 高度 | none、low、med、high |
none;绘制可见表面的元素拥有阴影 |
已发布的家族轴;ToggleButton 的采用已获批准 |
| grouping | 独立、间隔集合、连接表面 | 语义和绘制的包含关系决定归属;仅凭分组本身不决定 | 家族规则 |
跨组件不变式¶
- FR1 — 每个控件都有可访问的名称。 Button 家族控件必须(MUST)接收非空的可访问
label。文本控件渲染该标签或调用方提供的可见内容。纯图标控件通过aria-label暴露标签;其图标不能替代程序化名称。 - FR2 — 原生动作语义是默认行为。 瞬时或持续动作渲染为可操作按钮,具备键盘激活、焦点可见反馈和
type="button",除非组件的文档化表单模式另有说明。Button 的href模式是显式导航变体,并同样遵循family:navigation-destinations。 - FR3 — 禁用即不可操作。 禁用成员不得(MUST NOT)调用其回调或 Action。禁用成员保持可聚焦,并遵循
spec:AST-085。组的禁用状态覆盖成员可用性。 - FR4 — 待处理反馈保持用途和几何形态不变。 当成员暴露加载或 Action 时,待处理工作必须(MUST)设置
aria-busy,保持控件尺寸稳定,并显示 Spinner 而不改变可访问用途。显式的禁用样式和待处理样式保持不同。 - FR5 — 回调和 Action 的执行顺序一致。 当成员同时暴露同步回调和 Action 时,回调先执行。阻止该事件即阻止 Action。独立 ToggleButton 会在
pressedChangeAction之前同步运行onPressedChange,并在回调调用preventDefault()时跳过 Action。未提供回调时 Action 仍会运行。独立 ToggleButton 上的调用方onClick在onPressedChange和pressedChangeAction之前运行。当该onClick调用preventDefault()时,激活不请求下一个状态,两者都不运行;否则切换继续。调用方onClick绝不替代切换请求。没有pressedChangeAction时,仅回调激活必须(MUST)保持同步,且不报告 Action 待处理反馈。一次性 Action 在待处理期间对激活去重;显式可中断的持续 Action 可以接受新激活并替换在途意图。 - FR6 — 持续状态是显式且可逆的。 ToggleButton 必须(MUST)通过
aria-pressed暴露其有效状态,并在激活时请求下一个受控值。待处理状态可以是乐观的,但新的激活必须(MUST)基于有效的在途值,而不是过时的已提交值。 - FR7 — 共享尺寸保持家族几何形态。 使用家族尺寸轴的成员必须(MUST)将
sm、md、lg映射到相同的控件高度约定。纯图标成员在解析尺寸下为正方形。Button 和 IconButton 必须(MUST)将其所属图标槽中的 Astryx Icon 默认为:sm和md控件用sm,lg控件用md;显式 Icon 尺寸必须(MUST)优先。标签字重、按下状态、加载或图标替换不得(MUST NOT)改变外部控件尺寸。 - FR8 — 高程属于绘制的表面。 绘制自身可见表面的独立成员拥有其静止高程。绘制一个连续表面的连接组拥有一个共享高程,其成员绘制有效高程
none。不绘制共享表面的语义或布局组不得(MUST NOT)仅因包含按钮而获得高程。 - FR9 — 高程独立于交互状态。 按下、悬停、聚焦、激活、加载、禁用和图标状态不得(MUST NOT)改变高程的拥有者或层级。它们可以改变该表面上绘制的处理方式。
- FR10 — 公开状态、渲染状态和主题状态一致。 当成员暴露家族视觉轴时,其公开 prop、有效的渲染
data-*状态和文档化的主题视觉 prop 必须(MUST)描述其实际绘制的值。包装器不得(MUST NOT)将被忽略的子级值报告为有效输出。 - FR11 — 按钮专用组只有一个可访问的拥有者。 ButtonGroup 和 ToggleButtonGroup 必须(MUST)暴露可访问的组标签,并传播其文档化的尺寸和禁用默认值,同时不删除成员的可访问名称。该组仅拥有其组模式声明的行为和表面,以及
family:action-groups赋予它的跨成员按下跟踪。ToggleButtonGroup 中由value标识的成员必须(MUST)从该组派生按下状态和选择请求,而非其独立的isPressed、onPressedChange或pressedChangeAction。成员的onPressedChange和pressedChangeAction被忽略。成员激活不得(MUST NOT)启动成员 Action 或报告成员 Action 待处理反馈。 - FR12 — 连接组和间隔组保持不同。 ButtonGroup 的连接式呈现会移除成员间间隙、共享外边缘、拥有一个高程,并使用其文档化的 roving-focus 键盘模型。当前 ToggleButtonGroup 保持由间隙分隔的独立子表面;每个子级可以拥有自己的高程,包装器不拥有阴影。未来的连接式切换呈现必须(MUST)将高程移至该组,并使成员变平。
允许的组件变体¶
- AV1 — 瞬时动作与持续动作。 Button 和 IconButton 不保留按下状态。ToggleButton 拥有
isPressed、onPressedChange、pressedChangeAction以及按下状态的呈现。 - AV2 — 可见内容与仅图标内容。 Button 可以渲染可见标签、自定义可见内容、前导图标和尾部内容。IconButton 始终渲染一个必需的图标,且没有可见标签。ToggleButton 可以使用可见内容或仅图标内容,并可在按下时替换其图标。
- AV3 — 视觉强调。 Button 和 IconButton 暴露 Button 变体映射。ToggleButton 拥有自己的选中/按下处理,而不是创造一种瞬时动作层级。主题可以改变外观,但不改变这些语义。
- AV4 — 导航。 当提供
href时,Button 和 IconButton 可以渲染为链接。ToggleButton 仍然是带有aria-pressed的动作;由其 Action 支持的导航不会把控件变成目标链接。 - AV5 — 分组键盘模型。 ButtonGroup 可以对连接的动作集群使用漫游焦点。ToggleButtonGroup 保留为其按下按钮集合记录的键盘和选择行为。仅凭视觉相似性并不要求两个组使用相同的复合控件模型。
- AV6 — 工具提示所有权。 组件可以要求显式工具提示,或为仅图标用途提供文档化的自动工具提示。无论哪种方式,无障碍标签都是必需的。
代表性矩阵¶
| 成员与状态 | 共享不变量 | 有意变体 |
|---|---|---|
component:Button / 普通动作 |
具备命名、尺寸、可聚焦的动作表面;一次性触发的 pending 行为 | 可见内容、变体、表单类型和可选链接模式 |
component:IconButton / 紧凑动作或 FAB |
Button 行为、方形几何、组件族高度 | 必需图标;标签是程序化的而非可见的 |
component:ToggleButton / 按下与未按下 |
Button 的几何、命名、焦点、pending 和表面所有权 | 受控 aria-pressed、按下图标/处理、可中断的 Action |
component:ButtonGroup / 水平或垂直 |
带标签的组;继承尺寸/禁用状态 | 连接边缘、单一共享高度、漫游焦点 |
component:ToggleButtonGroup / 单选或多选 |
带标签的组;继承尺寸/禁用状态 | 选择所有者;子表面间隔布局;无外层高度 |
| 未来连接的切换组 | 带标签的选择组和按下语义 | 单一绘制分组表面拥有高度;成员不绘制任何高度 |
采用情况与例外¶
| 组件 | 当前采用情况 | 差距或例外 |
|---|---|---|
component:Button |
拥有共享表面、尺寸、状态、Action、链接和高度机制 | 链接模式另外遵循 family:navigation-destinations |
component:IconButton |
继承 Button 属性,并始终选择仅图标呈现 | 工具提示仍作为明确的消费者指导 |
component:ToggleButton |
继承 Button 的几何、焦点、pending 呈现和渲染高度状态 | 已批准的采用差距:添加现有的可选 elevation 属性和匹配的主题元数据 |
component:ButtonGroup |
连接表面、继承的尺寸/禁用状态、共享高度和漫游焦点 | 成员高度在连接时被有意抑制 |
component:ToggleButtonGroup |
受控单选/多选、继承的尺寸/禁用状态和间隔布局 | 外层不是绘制表面,因此不暴露任何组件族高度 |
ToggleButton 的高度是一个已获批准的实现差距。添加现有的可选 Elevation 轴可在不改变无属性渲染的前提下恢复组件族一致性。其当前的透明表面被接受,但并不声称透明性问题已解决;阴影可提供浮起边界,任何后续的填充或轮廓处理均需单独进行视觉审查。
验证映射¶
| 契约 | 验证 | 代表性成员与状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3 | 角色/名称、键盘、回调、禁用和禁用原因测试;原生禁用断言待符合性确认(spec:AST-085) |
文本 Button、IconButton、ToggleButton、链接模式、成员/组禁用 | 成员丢失其名称、键盘路径,或在禁用状态下被触发 |
| FR4–FR6 | ToggleButton.test.tsx:回调/Action 顺序与取消、仅回调的无 pending 路径、仅 Action 的落定,以及乐观重点击测试 |
独立的 ToggleButton,带任一/两个回调;Button 的 fire-once Action | 回调被丢弃、空 Action 报告忙碌、取消被绕过,或陈旧状态胜出 |
| FR7 | 单元测试加真实浏览器几何检查 | 所有尺寸;纯文本/纯图标;按下/未按下;加载中 | 家族成员高度不一致、纯图标不再保持正方形,或状态改变外部尺寸 |
| FR8–FR10 | data attribute、主题元数据与计算阴影测试 | 独立的 Button/IconButton/ToggleButton;相连与间隔分组;每个 elevation 层级 | 阴影落在错误的盒子上、状态改变深度,或 public/theme/rendered 值不一致 |
| FR11–FR12 | 分组语义、传播、DOM、键盘与渲染表面测试;ToggleButton.test.tsx 分组所有权用例 |
单选/多选,带成员回调/Action 与父级延迟接受;相连/间隔分组 | 成员回调或 Action 与分组状态竞争,或表面所有权被混淆 |
决策链接¶
spec:AST-002/DEC-1— 公共 API 的准入是显式且有证据支持的。family:navigation-destinations— Button 链接模式保留共享的导航安全契约。
未决问题¶
无。
内容边界¶
本文件仅负责跨组件的 Button 家族行为。组件专属的 prop 表、回调载荷类型、选择算法、变体、tooltip 策略、分组布局、实现机制、当前审计结果与产品专属的操作层级,仍归属于各自的组件、架构、设计、审计或调用点(callsite)所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx