@fuxishi/svg-icon：一个 Vue 3 svg本地图标+iconify图标组件库，让图标管理不再头疼

@fuxishi/svg-icon：一个 Vue 3 图标组件库，让图标管理不再头疼

前言

在 Vue 3 项目中使用图标，你是不是也遇到过这些问题：

Element Plus 图标、Ant Design 图标、本地 SVG 图标......各用各的组件，用法不统一
想做一个图标选择器，得自己从零写搜索、分页、弹窗逻辑
本地 SVG 图标散落在各处，没有统一的命名规范和类型提示
切换 UI 框架时，图标相关的代码基本要重写一遍
用 vite-plugin-svg-icons 等插件封装本地 SVG 图标组件，需要手动写注册逻辑、封装组件、处理命名，配置繁琐
用 unplugin-icons 虽然能自动导入图标，但和本地 SVG 图标、图标选择器是割裂的，还得自己拼方案
现有方案要么只解决图标渲染，要么只解决本地 SVG 加载，缺少一个覆盖「渲染 + 本地 SVG + 图标选择器 + 类型提示」的完整方案

如果你有以上痛点，那 @fuxishi/svg-icon 可能正是你需要的。

GitHub：https://github.com/Fuxi-zy/fx-svg-icons

npm：https://www.npmjs.com/package/@fuxishi/svg-icon

在线文档：https://fuxi-zy.github.io/fx-svg-icons/

它是什么

@fuxishi/svg-icon 是一个 Vue 3 图标组件库，核心解决三个问题：

统一图标使用方式 --- 不管是 Iconify 图标集还是本地 SVG，都用同一个 <FxIcon> 组件
开箱即用的图标选择器 --- 内置 Element Plus、Naive UI、AntDv Next、TDesign 四套预设，自动检测当前 UI 框架
Vite 插件自动生成类型 --- 精确到每一个图标名的 TypeScript 类型声明，IDE 输入 ep: 就能提示所有 Element Plus 图标

核心特性

1. 统一的图标组件 FxIcon

所有图标用同一个组件，通过 name 属性区分来源：

vue 复制代码

<template>
  <!-- Iconify 图标集 -->
  <FxIcon name="ep:edit" />
  <FxIcon name="ant-design:home-outlined" />

  <!-- 本地 SVG 图标 -->
  <FxIcon name="svg:star" />

  <!-- 自定义大小和颜色 -->
  <FxIcon name="ep:delete" :size="24" color="#f56c6c" />
  <FxIcon name="svg:heart" size="48px" />
</template>

size 支持数字和字符串，数字自动加 px。color 默认跟随文字颜色（currentColor）。

2. 本地 SVG 自动加载

只需要把 SVG 文件放到指定目录，Vite 插件会自动扫描并注册：

复制代码

src/assets/svgs/
  ├── star.svg              → svg:star
  ├── heart.svg             → svg:heart
  ├── common/
  │   └── batch-processing  → svg:common-batch-processing
  ├── statusCode/404/
  │   └── not-found-01.svg  → svg:statusCode-404-not-found-01
  └── editor/
      └── bold.svg          → svg:editor-bold

目录层级用 - 连接，多深的目录结构都能自动映射。不需要手动 import 每一个 SVG 文件。

3. 图标选择器 FxIconSelect

这是我最喜欢的功能。一个组件搞定图标选择，而且会自动检测你用的是哪个 UI 框架：

vue 复制代码

<template>
  <FxIconSelect v-model="selectedIcon" placeholder="请选择图标" />
</template>

<script setup>
import { ref } from 'vue'
const selectedIcon = ref('')
</script>

就这一行代码，它会自动：

检测 UI 框架：Element Plus / Naive UI / AntDv Next / TDesign，自动匹配对应的组件预设
按 Tab 分组：不同来源的图标自动分组（Element Plus 图标、Ant Design 图标、本地 SVG......）
搜索过滤：支持模糊搜索图标名
分页展示：每页 30 个图标，滚动加载

如果你用的 UI 框架不在预设列表中，也没关系。FxIconSelect 采用 Headless 架构，核心逻辑通过 useIconSelect composable 暴露，你可以完全自定义 UI。

4. Vite 插件自动生成类型

这是开发体验最好的部分。配置好插件后：

ts 复制代码

// vite.config.ts
import { fxDtsPlugin } from '@fuxishi/svg-icon/vite'

export default defineConfig({
  plugins: [
    vue(),
    fxDtsPlugin({
      svgGlobPattern: '/src/assets/svgs/**/*.svg',
      dtsDir: '@/types',
      splitDts: true,
    }),
  ],
})

插件会自动：

扫描 @iconify-json/* 包：读取你安装的所有图标集
扫描本地 SVG：根据 glob 模式扫描本地 SVG 文件
生成精确的类型声明：为每个图标名生成字面量类型

效果就是：在模板中输入 name="ep:" 后，IDE 会自动列出所有 Element Plus 图标名。不是 string 类型，而是精确到 "ep:edit" | "ep:delete" | "ep:search" | ... 的字面量联合类型。

安装了 @iconify-json/ep 就会生成 Element Plus 的类型，安装了 @iconify-json/ant-design 就会生成 Ant Design 的类型，完全按需。

5. 支持 Iconify 海量图标集

Iconify 是目前最大的开源图标集合，包含 100+ 图标集、200,000+ 图标。@fuxishi/svg-icon 支持所有 @iconify-json/* 包：

bash 复制代码

# 安装你需要的图标集
pnpm add @iconify-json/ep           # Element Plus 图标
pnpm add @iconify-json/ant-design   # Ant Design 图标
pnpm add @iconify-json/mdi          # Material Design 图标
pnpm add @iconify-json/carbon       # Carbon 图标
# ... 更多图标集

安装后在模板中就能直接使用，类型提示也会自动更新。

快速上手

安装

bash 复制代码

pnpm add @fuxishi/svg-icon

配置 Vite 插件

ts 复制代码

// vite.config.ts
import { fxDtsPlugin } from '@fuxishi/svg-icon/vite'

export default defineConfig({
  plugins: [
    vue(),
    fxDtsPlugin({
      svgGlobPattern: '/src/assets/svgs/**/*.svg', // 本地 SVG 目录
      dtsDir: '@/types',                            // 类型声明输出目录
      splitDts: true,                               // 按图标集拆分类型文件
    }),
  ],
})

注册组件

ts 复制代码

// main.ts
import { createApp } from 'vue'
import { setupIcons } from 'virtual:fx-svg-icon'
import App from './App.vue'

const app = createApp(App)
setupIcons(app) // 一行搞定：注册组件 + 加载图标数据 + 加载本地 SVG
app.mount('#app')

setupIcons 是由 Vite 插件生成的虚拟模块，它会自动：

注册 FxIcon 和 FxIconSelect 全局组件
加载所有已安装的 @iconify-json/* 图标数据
通过 import.meta.glob 加载本地 SVG 图标

开始使用

vue 复制代码

<template>
  <FxIcon name="ep:home-filled" :size="32" color="#409eff" />
  <FxIcon name="svg:star" size="32px" />
  <FxIconSelect v-model="icon" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
const icon = ref('')
</script>

在线示例

以下是不同 UI 框架下的图标选择器效果：

适用场景

后台管理系统 --- 图标选择器非常适合权限配置、菜单编辑等需要选择图标的场景
组件库 / 设计系统 --- 统一的图标组件，支持多框架预设
低代码平台 --- Headless composable 方便自定义 UI
任何需要大量使用图标的 Vue 3 项目

总结

@fuxishi/svg-icon 的核心价值在于：

能力	说明
统一接口	Iconify 图标 + 本地 SVG 用同一个组件
图标选择器	内置 4 套 UI 框架预设，自动检测，Headless 可扩展
自动类型	Vite 插件扫描生成精确到图标名的 TypeScript 类型
零配置 SVG	放文件到目录即可使用，自动扫描和命名

如果你正在寻找一个 Vue 3 图标解决方案，不妨试试。

链接

GitHub：https://github.com/Fuxi-zy/fx-svg-icons
npm：@fuxishi/svg-icon
在线文档：https://fuxi-zy.github.io/fx-svg-icons/