# SvgIcon 图标组件使用指南

`SvgIcon` 是本项目统一使用的图标组件，底层基于 `@iconify/vue`，支持渲染 **Iconify 开源图标** 和 **本地 SVG 图标**。

## 1. 快速开始

### 1.1 使用 Iconify 图标 (推荐)

本项目集成了 [Iconify](https://iconify.design/)，可直接使用海量开源图标库（如 Material Design, Carbon, Phosphor 等）。

**语法**：

```vue
<SvgIcon icon="图集名:图标名" />
```

**示例**：

```vue
<!-- Material Design Icons -->
<SvgIcon icon="mdi:home" class="text-xl text-blue-500" />

<!-- Carbon Icons -->
<SvgIcon icon="carbon:user" />
```

### 1.2 使用本地 SVG 图标

当需要使用设计师提供的自定义图标或彩色图标时。

1. **存放**：将 `.svg` 文件放入 `src/assets/svg-icon/` 目录。
2. **引用**：使用 `local-icon` 属性引用文件名（不含 `.svg` 后缀）。

**语法**：

```vue
<SvgIcon local-icon="文件名" />
```

**示例**：
假设文件位于 `src/assets/svg-icon/custom-logo.svg`：

```vue
<SvgIcon local-icon="custom-logo" class="text-32px" />
```

---

## 2. 属性说明 (Props)

该组件定义在 `src/components/custom/svg-icon.vue`。

| 属性名      | 类型     | 必填 | 默认值 | 说明                                         |
| :---------- | :------- | :--- | :----- | :------------------------------------------- |
| `icon`      | `string` | 否   | -      | Iconify 图标名称，格式为 `collection:name`。 |
| `localIcon` | `string` | 否   | -      | 本地 SVG 文件名。**优先级高于 `icon`**。     |

> **提示**：
>
> - 组件设置了 `inheritAttrs: false`，但会手动绑定 `class` 和 `style` 到根元素。
> - 你可以通过 Tailwind CSS 类名（如 `text-xl`, `text-red-500`）直接控制图标的大小和颜色。

---

## 3. 如何查找与使用图标

推荐使用 [Icones.js.org](https://icones.js.org/) 图标搜索引擎。

### 3.1 查找步骤

1. 打开 [Icones.js.org](https://icones.js.org/)。
2. 输入关键词搜索（如 `user`, `setting`）。
3. 点击选中的图标，复制底部的 **ID**（例如 `mdi:shield-airplane-outline`）。

### 3.2 使用示例对照

| Icones 图标 ID                                 | 在本项目中的写法 (推荐)                                           |
| :--------------------------------------------- | :---------------------------------------------------------------- |
| `mdi:shield-airplane-outline`                  | `<SvgIcon icon="mdi:shield-airplane-outline" />`                  |
| `material-symbols:android-wifi-4-bar-question` | `<SvgIcon icon="material-symbols:android-wifi-4-bar-question" />` |
| `solar:minimize-square-minimalistic-outline`   | `<SvgIcon icon="solar:minimize-square-minimalistic-outline" />`   |
| `tabler:align-box-top-right`                   | `<SvgIcon icon="tabler:align-box-top-right" />`                   |

---

## 4. 常见问题与进阶

### 4.1 什么是 `icon-ic-baseline-refresh`？

在项目中（如 `competition-add/index.vue`）你可能会看到这种写法：

```vue
<icon-ic-baseline-refresh class="text-icon" />
```

这是 `unplugin-icons` 插件提供的**自动组件导入**功能。

- **命名规则**：`{Prefix}-{Collection}-{Name}`
- **配置来源**：`.env` 文件中的 `VITE_ICON_PREFIX=icon`。
- **解析**：`icon-ic-baseline-refresh` 对应图集 `ic` 下的 `baseline-refresh` 图标。

**建议**：虽然支持这种写法，但为了统一性和灵活性（支持动态变量），**推荐统一使用 `<SvgIcon />` 组件**。

### 4.2 在 Render 函数中使用 (TSX)

在 Naive UI 的 `NTree`, `NDataTable` 或 `NMenu` 等需要渲染函数的场景中：

```ts
import { h } from 'vue'
import SvgIcon from '@/components/custom/svg-icon.vue'

// 渲染 Iconify 图标
function renderIcon() {
  return h(SvgIcon, {
    icon: 'carbon:folder',
    class: 'text-gray-500'
  })
}

// 渲染本地图标
function renderLocalIcon() {
  return h(SvgIcon, {
    localIcon: 'custom-logo'
  })
}
```
