图标按钮 · IconButton
使用图标表达紧凑操作，必须保留明确的可访问名称。
安装与前置条件
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。
示例与使用方式
- 图标按钮 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
- 图标按钮 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 图标按钮 · 浮动 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 图标按钮 · 加载状态 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 图标按钮 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
API 与上游详细参考
优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。
Icon Button
A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string | Accessible label. Used as aria-label (not rendered as visible text). | |
| icon * | ReactNode | Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons. | |
| variant | 'primary' | 'secondary' | 'ghost' | 'destructive' | 'secondary' | Visual style variant. |
| size | 'sm' | 'md' | 'lg' | 'md' | Size variant. |
| elevation | 'none' | 'low' | 'med' | 'high' | 'none' | Resting shadow depth. The most common FAB shape is an icon-only button, so raise it with low/med/high for a floating action button. none is the default flat button. |
| isLoading | boolean | false | Shows a loading spinner and disables interaction. |
| isDisabled | boolean | false | Disables the button. |
| tooltip | string | Tooltip text shown on hover. | |
| onClick | (e: MouseEvent) => void | Standard click handler. | |
| clickAction | (e: MouseEvent) => void | Promise<void> | Async click handler with automatic loading state. |
使用建议
- Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.
- Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.
- Use ghost in toolbars and dense areas to reduce visual clutter.
- 避免：Use IconButton if the action isn't obvious from the icon alone; use Button with text.
- 避免：Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.
无障碍
- Essential icon or spinner arc: IconButton has no visible label. Its icon must have at least 3:1 contrast with the button background in Rest, Hover, and Pointer down. The moving spinner arc must also meet 3:1 while loading. — 3:1
- Visible control boundary: The button edge needs 3:1 contrast only when users need it to see the control. — 3:1 if needed
- Keyboard focus indicator: The focus outline must have at least 3:1 contrast with the area around the button. Check the red outline on destructive buttons too. — 3:1
- Disabled appearance: Disabled controls do not need to meet these contrast ratios. — Not required
完整示例的额外依赖
部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：
npm install @heroicons/react@2.2.0