# Admin-UI 图标体系说明文档

> 本文档记录 admin-ui 图标配置、映射规则及相关注意事项，避免每次重复分析代码。

---

## 一、图标体系概览

admin-ui 支持 **两类图标**，由 `RuiIcon.vue` 组件统一处理：

| 类型 | 格式示例 | 来源 | 渲染方式 |
|------|---------|------|---------|
| **Element Plus 图标** | `Setting`、`UserFilled`、`HomeFilled` | `@element-plus/icons-vue` | `<el-icon>` |
| **Tabler 图标（Iconify）** | `tabler:settings`、`tabler:users` | `@iconify/vue` | `<Icon :icon="..." />` |

**判断规则**（`RuiIcon.vue`）：
- 如果字符串包含 `:` → 使用 Iconify 渲染（Tabler 图标）
- 否则 → 使用 Element Plus 图标组件渲染

---

## 二、图标选择器

**文件位置**：`admin-ui/src/components/IconPicker.vue`

**支持四类图标**：
1. **Element Plus** - 动态读取 `@element-plus/icons-vue` 全部图标
2. **Tabler** - 硬编码 102 个常用图标，以 `tabler:` 为前缀
3. **SVG** - 内联 SVG 代码
4. **图片/URL** - 粘贴图片 URL

**推荐使用 Tabler 图标**（`tabler:` 前缀），与后端菜单存储格式保持一致。

---

## 三、后端菜单图标存储格式

**当前标准**：所有菜单图标统一使用 `tabler:` 前缀格式

**示例**：
```
tabler:settings       → 系统管理
tabler:users          → 用户管理
tabler:menu-2         → 菜单管理
tabler:user-shield    → 角色管理
tabler:building       → 部门管理
tabler:book           → 字典管理
tabler:id             → 岗位管理
tabler:gift           → 租户套餐
tabler:shield-check   → 数据权限
tabler:award          → 用户等级
tabler:history        → 等级日志
tabler:device-desktop → 演示中心
tabler:palette        → 图标演示
tabler:list           → 列表演示
```

**历史变更**：
- 早期使用 Element Plus 图标组件名（如 `SettingOutlined`）
- 已执行升级脚本 `sql/update_menu_icon.sql` 统一改为 `tabler:` 格式

---

## 四、前端图标映射规则

**文件位置**：`admin-ui/src/composables/useMenu.ts`

`getIconName()` 函数处理逻辑：
1. 如果 `icon` 字段以 `tabler:` 开头 → **直接透传返回**
2. 否则 → 按原有映射规则转换为 Element Plus 图标名

**注意**：
- 后端返回的 `icon` 字段应始终使用 `tabler:` 格式
- 前端布局文件（SideLayout/TopNavLayout/DoubleLayout）已改为使用 `RuiIcon` 组件渲染菜单图标，支持 `tabler:` 格式

---

## 五、布局文件中的图标渲染

**修改后的渲染方式**（统一使用 `RuiIcon`）：

```vue
<!-- SideLayout.vue / TopNavLayout.vue -->
<template #title>
  <RuiIcon v-if="item.icon" :icon="item.icon" :size="16" class="menu-icon" />
  <span>{{ item.title }}</span>
</template>

<!-- DoubleLayout.vue（图标栏） -->
<div class="icon-btn">
  <RuiIcon :icon="item.icon" :size="20" />
</div>
```

**样式适配**（确保图标颜色与菜单主题一致）：
```css
.menu-icon {
  margin-right: 5px;
  color: inherit;
}
```

---

## 六、新增功能时的图标规范

1. **优先使用 Tabler 图标**（`tabler:` 前缀）
2. **在 IconPicker 中添加**：如果 IconPicker 的 Tabler 列表中没有需要的图标，添加到 `IconPicker.vue` 的 `tablerIcons` 数组
3. **后端菜单配置**：在 `config/menus/*.json` 中配置图标时，使用 `tabler:xxx` 格式
4. **前端自动适配**：无需修改前端代码，`RuiIcon` 组件会自动识别并渲染

---

## 七、常见问题

### Q: 为什么菜单图标显示不出来？
A: 检查后端返回的 `icon` 字段格式：
- 正确：`tabler:settings`
- 错误：`settings`、`Setting`、`tabler-settings`

### Q: 如何查看所有可用的 Tabler 图标？
A: 在菜单管理页面点击图标选择器，切换到 "Tabler" 标签页查看。

### Q: 能否使用 Element Plus 图标？
A: 可以，但不推荐。如果必须使用，直接写图标组件名（如 `Setting`），不要加 `tabler:` 前缀。

---

> **维护提示**：本文档位于 `/docs/admin-ui-icon-guide.md`，修改图标体系时必须同步更新。