UIcon 与 LucideIcon

UIcon 默认使用内置 Lucide SVG，也可连接应用自己注册的图标加载器。图标显示不依赖运行时远程图标服务。

按钮图标

<script setup lang="ts">
import { useI18n } from 'vue-i18n'
import { UIcon } from '@uadmin/ui'

const { t } = useI18n({
  useScope: 'local',
  messages: {
    'zh-CN': { search: '搜索', refresh: '刷新' },
    'en-US': { search: 'Search', refresh: 'Refresh' },
  },
})
const emit = defineEmits<{ search: []; refresh: [] }>()
</script>

<template>
  <el-button @click="emit('search')">
    <UIcon name="search" :size="16" />
    {{ t('search') }}
  </el-button>
  <el-button :aria-label="t('refresh')" @click="emit('refresh')">
    <UIcon name="refresh-cw" :size="16" />
  </el-button>
</template>

SVG 使用 aria-hidden="true"，纯图标按钮的可访问名称应放在按钮上。不要只给 SVG 添加 title 后省略按钮名称。

UIcon API

Prop	类型	默认
name	string	必填
collection	string	'lucide'
size	number | string	'1em'；数字为 px
color	string	继承上下文颜色
strokeWidth	number | string	不覆盖图标原有线宽；自定义集合不使用此属性

没有自定义 slots、events 或实例方法。Lucide 名称支持 layout-dashboard 和 LayoutDashboard 等形式。常用图标同步可用，未命中会加载本地完整集合 chunk；仍找不到时 UIcon 回退为 circle-help。

自定义 SVG 集合

应用初始化时注册一次。body 只包含 SVG 内部节点，不能包外层 <svg>。

import { registerIconLoader, type IconData } from '@uadmin/ui'

const icons: Record<string, IconData> = {
  mark: {
    width: 24,
    height: 24,
    body: '<path fill="currentColor" d="M12 2 22 12 12 22 2 12Z"/>',
  },
}
registerIconLoader('brand', name => icons[name] ?? null)

<UIcon collection="brand" name="mark" :size="24" />

IconLoader 可以返回 IconData | null 或其 Promise。未注册集合、返回 null 或加载失败时回退 circle-help。加载器直接提供的 SVG 会通过 v-html 渲染，仅使用应用信任的 SVG 内容，不要把用户提交的字符串直接作为 body。

直接使用 LucideIcon

import { LucideIcon, hasLucideIcon, loadFullLucideSet } from '@uadmin/ui'

await loadFullLucideSet()
const available = hasLucideIcon('search')

LucideIcon 的 props 是 name（必填）、size=16、strokeWidth?、fallback='circle'；颜色用 CSS 的 color。hasLucideIcon 只查询当前已加载的数据，不会自动加载完整集合。loadFullLucideSet() 缓存加载 Promise，无需反复请求。

不要假设 UIcon collection="logos" 会自动安装或下载第三方图标包：集合必须先注册。相关：组件选型 · 面包屑