---
url: /components/icon.md
---
# Icon 图标

语义图标组件。图标体系基于 [Remix Icon](https://remixicon.com/)（Remix Icon License v1.0，可免费商用）静态内置，共 **441 个单色图标**，键名为 kebab-case 语义命名，运行时零依赖。覆盖方向/状态/操作/数据展示、商务与财务（支付、购物、图表）、Logo 品牌（微信/支付宝/钉钉/GitHub 等）、开发、设备、媒体、地图出行等常用类目。

解析优先级：**custom（运行时注册）→ 内置 SVG（Remix 单色，含文件类型别名）→ 完整图标库**。SVG 填充使用 currentColor，颜色自动跟随上下文文字色，可用 `color` 覆盖；`size` 控制大小，渲染在行内 `i` 元素上。

## 基础用法

`size` 控制大小（数字按 px，也可传 '1em' 等字符串）。图标填充使用 `currentColor`：**不传 `color` 时自动继承父级文字颜色**——下面的铃铛放在主色文字里就呈现主色，「通知」是图标 + 文字同色的常见用法。

## 支付与品牌 Logo

内置常用支付渠道、社交平台与开发品牌 Logo（Logos 类目），适合收银台、渠道配置、OAuth 登录等场景：

## 商务与财务

收银、账单、图表、组织人事等 B 端高频图标：

## 完整图标库（加载全部 Remix 3229 个）

除核心内置图标外，Remix Icon 全量 3229 个图标（line/fill 全风格、原生命名，如 `checkbox-multiple-line`）以独立产物按需提供，**不占主包体积**：

```js
// 方式一：异步自愈 —— 什么都不用做
// eb-icon 同步未命中时自动按需加载完整库并补渲染（负缓存防重复加载）

// 方式二：显式预载（推荐在应用启动后台执行，或图标选择器打开时调用）
import { loadFullIcons } from '@wil-works/evoke-business-ui/full-icons'

loadFullIcons() // 幂等；完成后全部 Remix 原生名称可同步渲染
```

加载后即可枚举与检索：`getIconNames('full')` 返回全部原生命名；`getIconByNameAsync(name)` 异步安全获取。

## 尺寸与颜色

`color` 接受任意 CSS 颜色值，优先级高于上下文 currentColor；`name` 也可直接传图标组件对象。

## 图标总览

全部内置图标（441 个）按类目分组展示的完整清单已独立成页：**[图标总览](/components/icon-gallery)**——支持按语义名 / Remix 原名搜索、点击复制名称、一键加载 Remix 全量 3229 个图标。

## 图标命名规范

* 键名为 **kebab-case 语义命名**，与组件其他 API 的命名风格一致
* 面性格图标直接以 `-filled` 后缀提供（如 `star-filled`、`circle-close-filled`），与线性格同名成对
* 方向语义统一为 chevron 折线形（`arrow-right` / `caret-right`），适合下拉展开、面包屑等 UI 语义
* 需要新增图标时，在组件库 `scripts/generate-remix-icons.mjs` 的 `MAPPING` 中登记 Remix 名称后执行 `pnpm gen:icons` 重新生成

## 文件类型图标

常用文件类型为单色 Remix 图标族，多个扩展名别名指向同一图标资源：

| 入口名 | 别名（均指向同一图标） |
| --- | --- |
| `file-excel` | `xlsx` / `xls` / `excel` / `type-xlsx` |
| `file-word` | `doc` / `docx` / `word` / `type-docx` |
| `file-ppt` | `ppt` / `pptx` / `type-pptx` |
| `file-pdf` | `pdf` |
| `file-zip` | `zip` / `rar` / `7z` |
| `file-music` | `mp3` / `audio` |
| `file-video` | `mp4` / `video` |
| `file-code` | `json` |
| `file-image` | `img` / `png` / `jpg` / `jpeg` / `gif` |
| `file-text` | `txt` / `md` / `type-md` |

## 自定义图标注册

通过 `registerIcons({ name: Component })`（从组件库入口导出）注册自定义图标：无前缀使用时优先级最高，可覆盖内置 SVG 的同名图标；使用 `custom:xxx` 前缀可显式指定自定义图标，避免与内置图标名冲突。配套 `getIconNames('custom' | 'remix' | 'all')` 可查询已注册的图标名（`'remix'` 为内置 SVG 图标集）。

## API

此外，组件库导出 `REMIX_ICON_META`（图标名 → `{ category, remix }` 分类元数据）与 `REMIX_ICON_VERSION`（Remix Icon 版本号），可用于构建图标选择器。