SVG Sprite 图标

使用 SVG 雪碧图技术管理本地图标资源，实现高效的图标加载和管理。

🌐 关于 SVG Sprite

SVG Sprite 是一种将多个 SVG 图标合并到单个文件中的技术，通过 <use> 元素引用特定图标。

🚀 基本使用

<script setup>
import { QxsIcon } from '@qxs-bns/components'
</script>

<template>
  <!-- 使用 SVG Sprite 中的图标 -->
  <QxsIcon icon="home" :size="24" />
  <QxsIcon icon="user" color="#409eff" />
  <QxsIcon icon="setting" :size="32" />
</template>

🔧 配置 SVG Sprite

1. 安装依赖

# 安装 vite-plugin-svg-icons
npm install -D vite-plugin-svg-icons

2. Vite 配置

// vite.config.ts
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'

export default {
  plugins: [
    createSvgIconsPlugin({
      // 指定需要缓存的图标文件夹
      iconDirs: [path.resolve(process.cwd(), 'src/assets/icons')],
      // 指定 symbolId 格式
      symbolId: 'icon-[dir]-[name]',
      // 自定义插入位置
      inject: 'body-last',
      // 自定义 DOM ID
      customDomId: '__svg__icons__dom__',
    }),
  ],
}

3. 注册 SVG 图标

// main.ts
import 'virtual:svg-icons-register'

📁 目录结构

src/
├── assets/
│   └── icons/           # SVG 图标目录
│       ├── home.svg
│       ├── user.svg
│       ├── setting.svg
│       └── common/      # 子目录
│           ├── edit.svg
│           └── delete.svg
└── ...

🎨 SVG 图标规范

图标设计要求

<!-- 标准的 SVG 图标格式 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
</svg>

图标优化

• 移除无用属性：删除 width、height、fill 等属性
• 使用 viewBox：确保设置正确的 viewBox
• 路径优化：使用工具优化 SVG 路径
• 统一尺寸：建议使用统一的 viewBox 尺寸（如 24x24）

🔍 图标命名规则

基本命名

• home.svg → icon="home"
• user.svg → icon="user"
• setting.svg → icon="setting"

子目录命名

• common/edit.svg → icon="common-edit"
• common/delete.svg → icon="common-delete"

🎯 优势

• 本地资源：无网络依赖，加载速度快
• 批量优化：一次性加载所有图标
• 缓存友好：浏览器可以有效缓存
• 版本控制：图标文件可以进行版本控制

⚠️ 注意事项

构建配置

• 正确配置：确保 vite-plugin-svg-icons 正确配置
• 路径设置：图标目录路径必须正确
• 注册引入：必须在入口文件中引入注册代码

图标管理

• 命名规范：建立清晰的图标命名规范
• 目录结构：合理组织图标目录结构
• 图标优化：定期优化 SVG 图标文件

性能考虑

• 图标数量：避免包含过多不使用的图标
• 文件大小：控制单个 SVG 文件的大小
• 按需加载：考虑按模块分组加载图标

🛠️ 工具推荐

SVG 优化工具

• SVGO：命令行 SVG 优化工具
• SVG-Optimizer：在线 SVG 优化工具
• Figma/Sketch：设计工具导出优化

图标管理

• Iconify：图标管理和转换工具
• IcoMoon：图标字体和 SVG 生成工具

🔧 高级功能

关于 QxsIcon 组件的高级功能（旋转、翻转、颜色等），请参考：

👉 QxsIcon 组件文档

💡 最佳实践

1. 统一规范：建立图标设计和命名规范
2. 定期维护：定期清理不使用的图标
3. 版本管理：对图标文件进行版本控制
4. 文档记录：维护图标使用文档