# 图标 · Icon

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

图标用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```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

Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| icon * | IconName \| ComponentType<SVGProps> |  | 语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。 |
| color | 'primary' \| 'secondary' \| 'tertiary' \| 'disabled' \| 'accent' \| 'success' \| 'error' \| 'warning' \| 'inherit' | 'inherit' | 映射到 Astryx 图标颜色令牌的颜色变体。 |
| size | 'xsm' \| 'sm' \| 'md' \| 'lg' | Contextual; otherwise 'md' | 图标尺寸。显式值优先。省略时，Icon 使用最近的 Astryx 所属组件为其图标槽提供的默认尺寸；如果没有上下文默认值，则回退为 md。 |
| label | string |  | 有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。 |
| xstyle | StyleXStyles |  | 用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。 |

### 使用建议

- Use semantic icon names when available; they adapt to theme changes automatically.
- Pair icons with text labels for accessibility; icon-only elements need an accessible label.
- Use color tokens for icon colors, not hardcoded hex values.
- Be mindful of context; decorative icons in compact components can distract rather than help.
- 避免：Use icons as the sole means of conveying meaning; always provide a text alternative.
- 避免：Resize icons with arbitrary pixel values; use the provided size props.
- 避免：Mix icon styles (e.g. outline and filled) within the same context.
- 避免：Render raw SVG elements; always wrap in Icon for consistent sizing and color.
- 避免：Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-icon",
      "visualProps": [
        "color",
        "size"
      ]
    }
  ]
}
```

### 组件结构

- **Glyph**: Visual symbol rendered for the selected icon.

---

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