✨ 特性

📦 安装

npm install @winner-fed/plugin-unicons# 或者yarn add @winner-fed/plugin-unicons# 或者pnpm add @winner-fed/plugin-unicons

🚀 使用

基础使用

// win.config.jsexportdefault{plugins:['@winner-fed/plugin-unicons']}

<template>  <div><!-- 使用在线图标库-->    <icon-mdi-home />    <icon-heroicons-outline-menu-alt-2 />    <icon-ri-apps-2-line /><!-- 使用本地自定义图标-->    <icon-win-custom-logo /><!-- 作为组件使用-->    <IconMdiHome />    <IconWinCustomLogo />  </div></template><script setup>importIconMdiHomefrom'~icons/mdi/home'importIconWinCustomLogofrom'~icons/win/custom-logo'</script>

本地图标

src/├── icons/│   ├── logo.svg│   ├── arrow.svg│   └── custom-icon.svg

<template>  <div><!-- 本地图标会自动添加 win 前缀-->    <icon-win-logo />    <icon-win-arrow />    <icon-win-custom-icon />  </div></template>

⚙️ 配置

基础配置

// win.config.jsexportdefault{plugins:['@winner-fed/plugin-unicons'],unIcons:{// 自定义图标目录include:['src/assets/icons'],// 自定义图标集合customCollections:{'my-icons':{'custom-icon':'<svg>...</svg>'}},// 自动安装autoInstall:true,// 默认样式类名defaultClass:'unicons-win',// 编译器类型compiler:'vue3',// SVG 优化配置svgOptimization:{// 优化级别：'none' | 'minimal' | 'balanced' | 'aggressive'level:'balanced',// 是否保留原始 SVG 数据（用于调试）preserveOriginal:false,// 自定义 SVGO 配置customConfig:{plugins:[// 自定义插件配置]}},// 以下是 unplugin-icons 支持的其他配置scale:1.2,iconifyApiEndpoint:'https://api.iconify.design',transform(svg,collection,icon){// 自定义图标转换逻辑returnsvg}}}

配置选项

插件专有配置

扩展配置

🎯 图标命名规则

在线图标库

本地图标

🎨 样式定制

.unicons-win {width:1em;height:1em;fill: currentColor;stroke: none;display: inline-block;vertical-align: middle;}

自定义样式

<template>  <icon-mdi-homeclass="my-icon" /></template><style>.my-icon {font-size:24px;color:#1890ff;}</style>

通过查询参数自定义

<script setup>importLargeIconfrom'~icons/mdi/home?width=2em&height=2em'importColoredIconfrom'~icons/mdi/home?color=red'</script>

🎨 SVG 优化策略

优化级别说明

none - 无优化

// win.config.jsexportdefault{unIcons:{svgOptimization:{level:'none'}}}

minimal - 最小优化

exportdefault{unIcons:{svgOptimization:{level:'minimal'}}}

balanced - 平衡优化（默认）

exportdefault{unIcons:{svgOptimization:{level:'balanced'// 默认值}}}

aggressive - 激进优化

exportdefault{unIcons:{svgOptimization:{level:'aggressive'}}}

自定义优化配置

exportdefault{unIcons:{svgOptimization:{level:'balanced',customConfig:{plugins:[// 添加自定义插件{name:'addClassesToSVGElement',params:{className:'my-custom-class'}},// 或者覆盖默认行为{name:'removeAttrs',params:{attrs:['data-custom']// 只移除特定属性}}]}}}}

调试优化效果

exportdefault{unIcons:{svgOptimization:{level:'balanced',preserveOriginal:true// 开发环境启用}}}

选择建议

🔧 高级用法

动态图标

<template>  <component:is="iconComponent" /></template><script setup>import {computed }from'vue'consticonName=ref('home')consticonComponent=computed(()=> {return ()=>import(`~icons/mdi/${iconName.value}`)})</script>

获取原始 SVG

<script setup>importRawIconfrom'~icons/mdi/home?raw'// RawIcon 是 SVG 字符串</script>

高级配置示例

// win.config.jsexportdefault{unIcons:{// 自定义图标转换transform(svg,collection,icon){// 为所有图标添加样式returnsvg.replace('<svg','<svg')},// 缩放所有图标scale:1.5,// 自定义图标集合customCollections:{'brand':{'logo':'<svg viewBox="0 0 24 24">...</svg>','mark':()=>import('./assets/mark.svg?raw')}},// JSX 模式（适用于 React）jsx:'react',// 自定义 Iconify API 端点iconifyApiEndpoint:'https://api.iconify.design'}}

📋 支持的图标库

🔍 常见问题

Q: 如何查找可用的图标？

Q: 本地图标不显示？

Q: 如何优化包体积？

Q: 支持 TypeScript 吗？

Q: 如何自定义图标颜色？

<icon-mdi-homestyle="color:red" />

Q: 如何使用 unplugin-icons 的其他配置？

exportdefault{unIcons:{// 任何 unplugin-icons 支持的配置transform:(svg)=>svg.replace('currentColor','#ff0000'),scale:2,jsx:'react'}}

Q: SVG 图标显示异常或样式丢失？

exportdefault{unIcons:{svgOptimization:{level:'minimal'// 或 'none'}}}

exportdefault{unIcons:{svgOptimization:{level:'balanced',customConfig:{plugins:[{name:'removeAttrs',params:{attrs:['data-*']// 只移除 data 属性，保留其他}}]}}}}

Q: 如何在不同环境使用不同的优化策略？

exportdefault{unIcons:{svgOptimization:{level:process.env.NODE_ENV==='production' ?'balanced' :'minimal',preserveOriginal:process.env.NODE_ENV==='development'}}}

🤝 贡献

📄 许可证