vifo
cc46e13503
- backend/guides/environment-setup.md: docs/init-database.sql → sql/init-database.sql - frontend/admin-ui-icon-guide.md: docs/sql/update_menu_icon.sql → sql/update_menu_icon.sql
130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
# 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`，修改图标体系时必须同步更新。
|