@zkong-core/svg-icons

一个支持单色和多色图标的 SVG sprite 图标系统，适用于 Vue 2 和 Vue 3 项目。

✨ 特性

• 🎨 双模式支持: 单色图标（可动态改变颜色）和多色图标（保持原有颜色）
• 🚀 高性能: 使用 SVG sprite 技术，所有图标只需加载一次
• 📦 按需加载: 使用 Vite/Webpack 的动态导入，只打包使用的图标
• 🔧 Vue 2/3 兼容: 同时支持 Vue 2.7+ 和 Vue 3
• 💪 TypeScript 支持: 提供完整的类型定义
• 🎯 零配置: 开箱即用，无需复杂配置

📦 安装

# pnpm (推荐)
pnpm add @zkong-core/svg-icons

# npm
npm install @zkong-core/svg-icons

# yarn
yarn add @zkong-core/svg-icons

🚀 快速开始

1. 注册插件

Vue 3:

import { createApp } from 'vue'
import App from './App.vue'
import SvgIconPlugin from '@zkong-core/svg-icons'

const app = createApp(App)
app.use(SvgIconPlugin)
app.mount('#app')

Vue 2:

import Vue from 'vue'
import App from './App.vue'
import SvgIconPlugin from '@zkong-core/svg-icons'

Vue.use(SvgIconPlugin)

new Vue({
  render: h => h(App),
}).$mount('#app')

2. 使用图标

<template>
  <div>
    <!-- 单色图标 - 可以改变颜色 -->
    <zk-svg-icon icon-class="back" :size="24" color="#409EFF" />
    
    <!-- 多色图标 - 保持原有颜色 -->
    <zk-svg-icon icon-class="logo" :size="32" />
    
    <!-- 旋转动画 -->
    <zk-svg-icon icon-class="loading" :size="20" spin />
    
    <!-- 兼容旧的命名方式 -->
    <icon-svg icon-class="home" :size="18" />
  </div>
</template>

📖 API

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | icon-class | String | - | 图标名称（必填，对应文件名） | | size | Number \| String | 18 | 图标大小（如 20、"24px"） | | color | String | 'currentColor' | 图标颜色（仅对单色图标有效） | | spin | Boolean | false | 是否启用旋转动画 |

📁 图标类型

单色图标（Monochrome Icons）

存放位置: src/icons/mono/

特点:

• ✅ 可以通过 color prop 动态改变颜色
• ✅ 适合界面图标、操作按钮等
• ⚠️ SVG 中的 fill 和 stroke 属性会被自动移除

使用示例:

<!-- 红色图标 -->
<zk-svg-icon icon-class="back" color="red" :size="20" />

<!-- 蓝色图标 -->
<zk-svg-icon icon-class="user" color="#409EFF" :size="24" />

<!-- 继承父元素颜色 -->
<zk-svg-icon icon-class="home" :size="16" />

多色图标（Colored Icons）

存放位置: src/icons/colored/

特点:

• ✅ 保留 SVG 中的所有颜色信息
• ✅ 适合品牌 Logo、复杂插图等
• ⚠️ 不能通过 color prop 改变颜色

使用示例:

<!-- 多色图标，保持原有颜色 -->
<zk-svg-icon icon-class="logo" :size="32" />

🔧 添加自定义图标

方法 1: Fork 并添加到源码

1. Fork 本仓库
2. 将 SVG 文件添加到对应目录：
   • 单色图标: packages/svg-icons/src/icons/mono/
   • 多色图标: packages/svg-icons/src/icons/colored/
3. 运行 pnpm build 构建
4. 提交 PR

方法 2: 在项目中扩展

如果你想在自己的项目中添加图标而不修改包源码：

// 创建一个扩展文件 src/icons/custom-icons.js
import { injectSvgSprite } from '@zkong-core/svg-icons'

// 导入你的自定义图标
import customIcon1 from './custom-icons/icon1.svg?raw'
import customIcon2 from './custom-icons/icon2.svg?raw'

// 手动注入自定义图标
export function injectCustomIcons() {
  const div = document.createElement('div')
  div.innerHTML = `
    <svg xmlns="http://www.w3.org/2000/svg" style="display:none;">
      <symbol id="icon-custom1" viewBox="0 0 24 24">${customIcon1}</symbol>
      <symbol id="icon-custom2" viewBox="0 0 24 24">${customIcon2}</symbol>
    </svg>
  `
  document.body.appendChild(div)
}

// 在 main.js 中调用
import { injectCustomIcons } from './icons/custom-icons'
injectCustomIcons()

🎨 SVG 文件要求

单色图标

• 建议在 SVG 中使用 fill="currentColor"
• 或者不设置 fill 属性（构建时会自动移除）
• 确保 SVG 有 viewBox 属性

多色图标

• 保留所有颜色属性（fill, stroke 等）
• 确保 SVG 有 viewBox 属性以支持缩放

🔨 开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 发布
pnpm publish

📝 最佳实践

1. 图标命名规范

• 使用小写字母和连字符：user-info.svg
• 避免使用空格和特殊字符
• 名称要有意义，见名知意

2. SVG 文件优化

• 使用 SVGOMG 在线工具优化
• 移除不必要的元数据和注释
• 确保 SVG 有 viewBox 属性

3. 性能优化

• 尽量使用单色图标（文件更小）
• 复杂的多色图标考虑使用 PNG 或 WebP

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT