Files

T

vifo cc46e13503 docs: 更新 SQL 脚本目录引用路径

- 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

2026-06-05 06:56:53 +08:00

4.1 KiB

Raw Permalink Blame History

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

支持四类图标：

Element Plus - 动态读取 @element-plus/icons-vue 全部图标
Tabler - 硬编码 102 个常用图标，以 tabler: 为前缀
SVG - 内联 SVG 代码
图片/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() 函数处理逻辑：

如果 icon 字段以 tabler: 开头 → 直接透传返回
否则 → 按原有映射规则转换为 Element Plus 图标名

注意：

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

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

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

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

样式适配（确保图标颜色与菜单主题一致）：

.menu-icon {
  margin-right: 5px;
  color: inherit;
}

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

优先使用 Tabler 图标（tabler: 前缀）
在 IconPicker 中添加：如果 IconPicker 的 Tabler 列表中没有需要的图标，添加到 IconPicker.vue 的 tablerIcons 数组
后端菜单配置：在 config/menus/*.json 中配置图标时，使用 tabler:xxx 格式
前端自动适配：无需修改前端代码，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，修改图标体系时必须同步更新。

4.1 KiB Raw Permalink Blame History Unescape Escape