@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 图标组件库，核心解决三个问题：

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

核心特性

1. 统一的图标组件 FxIcon

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

<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 框架：

<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 架构，核心逻辑通过useIconSelectcomposable 暴露，你可以完全自定义 UI。

4. Vite 插件自动生成类型

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

// vite.config.tsimport{fxDtsPlugin}from'@fuxishi/svg-icon/vite'exportdefaultdefineConfig({plugins:[vue(),fxDtsPlugin({svgGlobPattern:'/src/assets/svgs/**/*.svg',dtsDir:'@/types',splitDts:true,}),],})

插件会自动：

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

效果就是：在模板中输入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/*包：

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

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

快速上手

安装

pnpmadd@fuxishi/svg-icon

配置 Vite 插件

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

注册组件

// main.tsimport{createApp}from'vue'import{setupIcons}from'virtual:fx-svg-icon'importAppfrom'./App.vue'constapp=createApp(App)setupIcons(app)// 一行搞定：注册组件 + 加载图标数据 + 加载本地 SVGapp.mount('#app')

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

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

开始使用

<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 框架下的图标选择器效果：

• Element Plus 示例
• Naive UI 示例
• AntDv Next 示例
• TDesign 示例

适用场景

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

总结

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

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

链接

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