跳转至

IconButton 组件契约

契约概览

Area Contract
公共契约 无变化。IconButton 接受 Button 的 props,但不包含 isIconOnly、children 和 endContent,且要求必须有 icon。
行为 IconButton 始终渲染 Button 的仅图标模式:一个默认方形的按钮,通过 aria-label 以 label 命名,没有可见文本。所有其他行为均与 Button 相同。
对最终用户的影响 用户看到的是一个紧凑、默认方形的操作,反馈与任何 Button 相同。屏幕阅读器用户会听到 label。有视力的用户只有在调用方添加提示时才能看到可见提示。
对构建者的影响 无。
兼容性/就绪状态 记录已发布的行为;无 API、默认值或 DOM 更改。Button 的链接模式焦点、减少动效和自着色内容缺口原样适用;这三项均列于“当前状态影响”之下。
评审检查 若 IconButton 渲染可见标签文本或结束内容、在默认宽高比且无 width 时不是方形、丢失其 aria-label,或行为与 Button 的仅图标模式不同,则应拒绝。
治理规则 family:buttons FR1, FR7, AV2, AV6; component:Button; spec:AST-085 FR1, FR4; design:reduced-motion DR1, DR3; architecture:component-size-cascade; architecture:public-component-api.

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

意图

IconButton 是 family:buttons 所命名的 Button 显式仅图标投影。它为调用方提供了一个可 grep 的组件,用于展示仅包含一个图标的紧凑操作,而无需创建第二种操作模型。消费者用法见 IconButton.doc.mjs。

兼容性与迁移

  • 已发布默认值保留:yes;默认值为 Button 的默认值
  • 兼容性类别:记录已发布行为;无公开 prop、默认值、导出或 DOM 更改
  • 受控/非受控行为:不适用
  • 迁移决策:无

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

所有权边界

拥有

  • 将 Button 的内容模式固定为仅图标。
  • prop 表面:必须提供 icon,且不接受 isIconOnly、children 或 endContent。

不拥有 / 非目标

  • 所有渲染行为:元素、命名规则、大小、默认方形几何、点击和 clickAction 处理、pending、disabled、链接模式、tooltip、elevation、反馈以及 button 主题目标——由 component:Button 拥有。
  • 由 label 自动生成的 tooltip——不提供;由调用方添加 tooltip(family:buttons AV6)。
  • 图标渲染——由 component:Icon 拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
仅图标模式 始终开启 图标是唯一可见内容。 所有变体、大小和状态。 开启 component:IconButton 稳定 TypeScript 拒绝 isIconOnly、children 和 endContent。
图标 调用方节点 可见字形;必需。 所有状态;pending 时隐藏在 Spinner 后面,除非它绘制自己的颜色(component:Button FR8 缺口)。 必需 component:IconButton 稳定 TypeScript 拒绝缺少 icon。

所有其他概念(variant、size、elevation、pending、availability、link mode、width、tooltip)均属于 Button,并采用 Button 的默认值。

行为与布局契约

ID 不变量 依据
FR1 IconButton 在仅图标模式下精确渲染一个 Button,包含调用方的 icon 和所有其他提供的 prop(包括 ref)。它不添加任何自己的元素、状态或行为。 family:buttons AV2;当前源码
FR2 当 label 非空时,通过 aria-label 提供无障碍名称,其值为 label;不渲染任何可见的标签文本。 family:buttons FR1;当前源码与测试
FR3 在默认的仅图标形态且调用方未指定 width 时,控件在解析后的尺寸下为正方形且无内边距。未指定显式尺寸的 Astryx 图标在 sm 与 md IconButton 中渲染为 sm,在 lg IconButton 中渲染为 md;显式指定的图标尺寸优先。 family:buttons FR7;当前测试
FR4 变体、尺寸、高度、onClick、clickAction、加载、禁用和按压反馈均遵循 component:Button,包括其实现缺口:禁用遵循 component:Button FR10,并在带 href 时遵循 FR11;加载遵循 FR8,在减少动态效果且使用精细指针时,其 Spinner MUST 立即出现(design:reduced-motion DR3);按压反馈遵循 FR15,其按压缩放 MUST NOT 在减少动态效果下生效(DR1)。 component:Button;design:reduced-motion;当前测试

允许的变体

  • AV1 — 图标内容。 任何调用方节点都可填充图标槽位;IconButton 不检查该内容。

代表性状态

状态 必要不变式 允许的变体
静止 默认正方形,以 label 命名;仅图标。 变体、尺寸、主题绘制。
浮动(高度) 所选层级在表面上的阴影。 层级。
加载中 Button 的挂起状态:Spinner、aria-busy、仍可聚焦。 Spinner 延迟。
已禁用 Button 的禁用状态(component:Button FR10)。 是否存在 Tooltip。

转换与优先级顺序

  • ORD1 — 内容模式。 始终仅图标;任何调用方属性都不能覆盖它。

性能与资源

  • PR1 — 不增加额外开销。 IconButton 在 Button 的基础上不增加任何状态、效果、监听器或元素。

无障碍契约

  • AR1 — 名称。 label 是唯一的无障碍名称;图标绝不可替代它(family:buttons FR1)。
  • AR2 — 可见提示。 IconButton 不显示任何可见文本。仅当调用方设置 tooltip 时才存在可见提示;除非该提示重复了 label,否则它也会描述该按钮(component:Button FR12)。
  • AR3 — 目标尺寸。 在默认正方形形态下,未指定 width 的最小 IconButton 为 28 × 28 CSS 像素,高于 WCAG 2.5.8 规定的 24 × 24 最小值。若调用方 width 或主题的仅图标形态将其缩小至 24 CSS 像素以下,则目标尺寸由该调用方或主题负责。
  • AR4 — 其余部分。 键盘、焦点指示器、加载播报以及忙碌或禁用状态的暴露均遵循 component:Button AR2–AR5。

设计关系

解剖结构或状态 设计要求 定义权威 层级角色 组件契约
方形表面 Button 表面,采用默认 1 / 1 宽高比,除非调用方 width 或主题宽高比改变它。 当前源码 显著 FR3
图标 唯一可见内容,尺寸由按钮决定。 当前源码与测试 显著 FR3

design:reduced-motion 控制 IconButton 继承的按压缩放(FR4)。没有其他设计记录控制 IconButton。IconButton 没有自己的主题目标;它渲染 Button 的 button 目标。

家族与系统关系

  • family:buttons 将 IconButton 命名为 Button 的显式仅图标投影;IconButton 通过 Button 采用 FR1、FR7、AV2 和 AV6。
  • component:Button 拥有 IconButton 展示的所有渲染行为。
  • spec:AST-085 通过 Button 应用;缺口记录在该处。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
spec:AST-085 记录了 IconButton 的继承缺口;component:Button AR4–AR5 和 FR10–FR15 覆盖除下方列出内容之外的所有行为状态和无障碍暴露。 全部,包括静止状态及每种继承状态。 未测试或未记录的大小与布局变更会被突变测试弱点捕获。 无障碍与加载部分。
--- --- --- --- ---
FR1、FR2 IconButton.test.tsx 的 label、visible-text、ref 和 displayName 用例 静止状态 可见的 label 文本不存在、aria-label 丢失或 ref 被丢弃时失败。 audit:IconButton/anatomy
FR3 IconButton.test.tsx 的图标尺寸用例 sm、md、lg;显式 Icon 尺寸 默认 Icon 尺寸错误或显式尺寸被覆盖时失败。 audit:IconButton/layout
FR3(方形) IconButtonAudit.a11y.chromium.spec.ts 的传感器记录 Neutral 和 Butter 主题下的 sm、md、lg,浅色和深色 盒子不是方形、Neutral 主题下出现 padding、图标不在中心,或 Neutral 主题下图标不是 16px(sm、md)或 20px(lg)时,记录失败。 audit:IconButton/layout
FR4 IconButton.test.tsx 的点击、禁用、加载和 elevation 用例 点击;禁用;加载;none 和 med elevation 点击未到达 onClick、禁用状态下仍触发点击、忙碌的 IconButton 缺少 aria-disabled,或两个 elevation 的 class 相同时失败。 audit:IconButton/behavior
FR4(variant、size) IconButton.test.tsx 的 variant 和 size 映射用例 每个 variant;每个 size 缺少或错误的 data-variant 或 data-size 会导致失败。 audit:IconButton/behavior
FR4(减少动态效果) 证据缺口:没有测试在 prefers-reduced-motion: reduce 下断言按压或加载结果。按压状态下的 IconButtonAudit.a11y.chromium.spec.ts 记录在减少动态效果开启时记录了发布版 0.98 按压缩放,这会使该条款失败;发布版 Spinner 的淡出效果也是如此。 鼠标和触摸按压;待处理的 clickAction,或使用精确指针的可中断加载 按压期间计算出的 transform 不是 none 或 scale(1),或加载开始后 Spinner 的 opacity 低于 1。 audit:IconButton/behavior
AR1、AR4 Button.a11y.test.tsx 和 Button.a11y.chromium.spec.ts 的 IconButton 状态 静止、禁用、加载中的 IconButton 缺少可访问名称,或可聚焦、可操作、不可用状态错误时失败。 audit:IconButton/accessibility
AR2, AR3 IconButton.test.tsx 的 tooltip-description 用例与 IconButtonAudit.a11y.chromium.spec.ts 的 sensor 回执 键盘聚焦时的工具提示;Neutral 主题下的 sm 未在聚焦时显示或描述按钮的工具提示,或默认宽高比下小于 28×28 CSS 像素的 sm 目标,均判为失败。 audit:IconButton/accessibility
ORD1 IconButton.test.tsx 调用方 isIconOnly 用例 调用方 isIconOnly={false} 可见的标签文本或丢失的 aria-label 判为失败。 audit:IconButton/behavior
PR1 证据缺口:没有测试断言 IconButton 不会增加额外工作 — — audit:IconButton/behavior

当前状态影响

  • 链接模式聚焦(FR4)。 处于聚焦状态的链接模式 IconButton 在变为禁用后,无论是否带有 tooltip 都会失去焦点,因为其锚点被替换为 <button>,正如 component:Button FR11 所记录。
  • 减弱动态效果(FR4)。 当用户偏好减弱动态效果时,独立的 IconButton 在按下时会缩放至 0.98,待处理 clickAction 或可中断 IconButton 的 Spinner 会淡入;正如 component:Button FR8 与 FR15 所记录,这与 design:reduced-motion 的 DR1 和 DR3 相悖。
  • 加载时自绘颜色的图标(FR4)。 自行绘制颜色的图标(例如图片或多色 SVG)在 Spinner 下方仍保持可见,正如 component:Button FR8 所记录。

决策日志

无组件本地决策。IconButton 应用 family:buttons 与 component:Button。

未决问题

无。

内容边界

本文件不重复使用者的属性表格/示例、当前审计结果、实现步骤或家族/系统规则,而是链接到其各自的所属文档。

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