跳转至

按钮家族契约

意图

无论一个动作是带标签的、纯图标的、持久的、独立的还是分组的,用户都应遇到一套连贯统一的按钮系统。成员共享相同的控件几何、可访问名称要求、交互反馈、异步动作模型和表面归属。每个成员仍保有自己的语义,分别对应瞬时动作、导航目标、持久按压状态或分组。

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