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:buttonsAV6)。 - 图标渲染——由
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:buttonsFR1)。 - AR2 — 可见提示。 IconButton 不显示任何可见文本。仅当调用方设置
tooltip时才存在可见提示;除非该提示重复了label,否则它也会描述该按钮(component:ButtonFR12)。 - AR3 — 目标尺寸。 在默认正方形形态下,未指定
width的最小 IconButton 为 28 × 28 CSS 像素,高于 WCAG 2.5.8 规定的 24 × 24 最小值。若调用方width或主题的仅图标形态将其缩小至 24 CSS 像素以下,则目标尺寸由该调用方或主题负责。 - AR4 — 其余部分。 键盘、焦点指示器、加载播报以及忙碌或禁用状态的暴露均遵循
component:ButtonAR2–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:ButtonFR11 所记录。 - 减弱动态效果(FR4)。 当用户偏好减弱动态效果时,独立的 IconButton 在按下时会缩放至 0.98,待处理
clickAction或可中断 IconButton 的 Spinner 会淡入;正如component:ButtonFR8 与 FR15 所记录,这与design:reduced-motion的 DR1 和 DR3 相悖。 - 加载时自绘颜色的图标(FR4)。 自行绘制颜色的图标(例如图片或多色 SVG)在 Spinner 下方仍保持可见,正如
component:ButtonFR8 所记录。
决策日志¶
无组件本地决策。IconButton 应用 family:buttons 与 component:Button。
未决问题¶
无。
内容边界¶
本文件不重复使用者的属性表格/示例、当前审计结果、实现步骤或家族/系统规则,而是链接到其各自的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx