winjs-plugin-unicons

一个为 WinJS 项目提供的图标解决方案，底层基于 unplugin-icons 插件，提供强大的图标管理和使用体验。

✨ 特性

• 📦 开箱即用 - 零配置即可使用数万个图标
• 🎯 多框架支持 - 支持 Vue2、Vue3 等主流框架
• 🛠️ 多打包工具 - 支持 Vite、Webpack、Rspack
• 🔧 自动导入 - 自动导入图标组件，无需手动注册
• 📁 本地图标 - 支持本地 SVG 图标自动优化和导入
• 🎨 自定义图标集 - 支持自定义图标集合
• ⚡ 按需加载 - 仅打包使用的图标，优化包体积
• 🎪 SVG 优化 - 自动优化 SVG 图标，移除冗余代码

📦 安装

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

🚀 使用

基础使用

1. 在配置文件中启用插件

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

2. 在组件中使用图标

<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>
import IconMdiHome from '~icons/mdi/home'
import IconWinCustomLogo from '~icons/win/custom-logo'
</script>

本地图标

将 SVG 图标文件放置在 src/icons 目录下，插件会自动：

1. 读取并优化 SVG 文件
2. 转换为可用的图标组件
3. 支持自动导入和按需加载

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.js
export default {
  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) {
      // 自定义图标转换逻辑
      return svg
    }
  }
}

配置选项

插件专有配置

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | include | string[] | ['src/icons'] | 自定义图标目录，会与默认的 src/icons 目录合并 | | customCollections | object | {} | 自定义图标集合 | | autoInstall | boolean | true | 自动安装图标组件 | | defaultClass | string | 'unicons-win' | 默认样式类名 | | compiler | string | 自动检测 | 编译器类型，支持 vue2、vue3 等 | | svgOptimization | object | { level: 'balanced' } | SVG 优化配置 | | svgOptimization.level | 'none' \| 'minimal' \| 'balanced' \| 'aggressive' | 'balanced' | 优化级别 | | svgOptimization.preserveOriginal | boolean | false | 是否保留原始 SVG 数据 | | svgOptimization.customConfig | object | undefined | 自定义 SVGO 配置 |

扩展配置

本插件基于 unplugin-icons，因此支持所有 unplugin-icons 的配置选项：

• scale - 图标缩放比例
• transform - 自定义图标转换函数
• iconifyApiEndpoint - Iconify API 端点
• jsx - JSX 模式配置
• 以及其他 unplugin-icons 支持的配置项

💡 提示: 所有传入的配置都会被传递给 unplugin-icons，让你能够使用其完整功能。

🎯 图标命名规则

在线图标库

格式：icon-{collection}-{name}

• icon-mdi-home → Material Design Icons 的 home 图标
• icon-heroicons-outline-menu → Heroicons 的 outline menu 图标
• icon-ri-apps-2-line → Remix Icons 的 apps-2-line 图标

本地图标

格式：icon-win-{name}

• src/icons/logo.svg → icon-win-logo
• src/icons/my-icon.svg → icon-win-my-icon

文件名会自动转换为驼峰命名：

• custom-icon.svg → customIcon
• user_profile.svg → userProfile

🎨 样式定制

插件自动注入基础样式：

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

自定义样式

<template>
  <icon-mdi-home class="my-icon" />
</template>

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

通过查询参数自定义

<script setup>
import LargeIcon from '~icons/mdi/home?width=2em&height=2em'
import ColoredIcon from '~icons/mdi/home?color=red'
</script>

🎨 SVG 优化策略

插件提供了多级 SVG 优化策略，让你在保证原始性和优化效果之间找到平衡：

优化级别说明

none - 无优化

• 完全保持 SVG 原始状态
• 不进行任何处理
• 适用于需要完全保留原始设计的场景

// win.config.js
export default {
  unIcons: {
    svgOptimization: {
      level: 'none'
    }
  }
}

minimal - 最小优化

• 只做基础清理（移除注释、元数据等）
• 保留所有样式相关属性（fill、stroke、class 等）
• 保留 viewBox、xmlns 等重要属性
• 推荐用于设计精美的图标

export default {
  unIcons: {
    svgOptimization: {
      level: 'minimal'
    }
  }
}

balanced - 平衡优化（默认）

• 适度优化，保留重要的样式属性
• 移除部分冗余属性，但保留 class 用于样式控制
• 在文件大小和原始性之间取得平衡
• 适用于大多数使用场景

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

aggressive - 激进优化

• 最大程度优化文件大小
• 移除 fill、stroke、class 等属性
• 可能改变图标的原始外观
• 适用于对文件大小要求严格的场景

export default {
  unIcons: {
    svgOptimization: {
      level: 'aggressive'
    }
  }
}

自定义优化配置

你可以通过 customConfig 提供自定义的 SVGO 配置：

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

调试优化效果

启用 preserveOriginal 选项可以在开发时对比优化前后的差异：

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

选择建议

| 场景 | 推荐级别 | 原因 | |------|----------|------| | 品牌图标、Logo | minimal | 保持设计完整性 | | 通用 UI 图标 | balanced | 平衡优化和兼容性 | | 大量简单图标 | aggressive | 最小化包体积 | | 复杂插画图标 | none 或 minimal | 避免破坏视觉效果 | | 生产环境 | balanced | 稳定可靠 |

🔧 高级用法

动态图标

<template>
  <component :is="iconComponent" />
</template>

<script setup>
import { computed } from 'vue'

const iconName = ref('home')
const iconComponent = computed(() => {
  return () => import(`~icons/mdi/${iconName.value}`)
})
</script>

获取原始 SVG

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

高级配置示例

// win.config.js
export default {
  unIcons: {
    // 自定义图标转换
    transform(svg, collection, icon) {
      // 为所有图标添加样式
      return svg.replace('<svg', '<svg class="custom-icon"')
    },
    
    // 缩放所有图标
    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'
  }
}

📋 支持的图标库

插件支持 Iconify 提供的所有图标库：

• Material Design Icons (mdi) - 7,000+ 图标
• Heroicons (heroicons) - 460+ 图标
• Remix Icons (ri) - 2,500+ 图标
• Feather Icons (feather) - 280+ 图标
• Ant Design Icons (ant-design) - 800+ 图标
• Carbon Icons (carbon) - 2,000+ 图标
• Tabler Icons (tabler) - 4,000+ 图标
• Font Awesome (fa, fa-solid, fa-regular, fa-brands) - 2,000+ 图标

更多图标库请访问：https://icon-sets.iconify.design/

🔍 常见问题

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

A: 访问 Iconify 浏览所有可用图标，或者在 icones.netlify.app 搜索。

Q: 本地图标不显示？

A: 请检查：

1. SVG 文件是否放在 src/icons 目录下
2. 文件名是否符合规范（仅包含字母、数字、连字符、下划线）
3. SVG 文件是否有效

Q: 如何优化包体积？

A: 插件默认按需加载，只会打包使用的图标。避免使用 import * from '~icons/*' 这样的全量导入。

Q: 支持 TypeScript 吗？

A: 完全支持！插件会自动生成类型定义。

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

A: 使用 CSS 的 color 属性：

<icon-mdi-home style="color: red" />

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

A: 插件支持 unplugin-icons 的所有配置选项，直接在 unIcons 配置中添加即可：

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

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

A: 这通常是由于 SVG 优化过度导致的。尝试以下解决方案：

1. 降低优化级别：

export default {
  unIcons: {
    svgOptimization: {
      level: 'minimal' // 或 'none'
    }
  }
}

2. 保留特定属性：

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

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

A: 可以根据环境变量动态配置：

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

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License