# 图标按钮 · IconButton

- 页面: https://jiguang132.com/zh/resources/astryx/docs/icon-button
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

使用图标表达紧凑操作，必须保留明确的可访问名称。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **图标按钮 · 综合展示 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


## 完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

```bash
npm install @heroicons/react@2.2.0
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt