v-icon-svg

渲染 SVG 图标字符串, 支持通过 CSS font-size 和 color 属性调整大小和颜色。

• Demo

快速开始

安装

pnpm add v-icon-svg
# or
npm i v-icon-svg

引入

import { SVGIcon } from 'v-icon-svg';

// vue2
import { SVGIcon } from 'v-icon-svg/vue2';

方案概览

本包提供两种使用方式：

| 方案 | 特点 | 适用场景 | | ----------------- | ------------------------------- | -------------------------------------- | | 🚀 运行时方案 | 直接传入 SVG 字符串，运行时处理 | 动态图标、第三方 SVG、灵活性要求高 | | ⚡ 构建时方案 | Webpack/Rspack 插件，构建时处理 | 静态图标资源、性能要求高、开发体验优先 |

🚀 运行时方案

在 Vue 模板中使用 SVGIcon 组件，通过 icon prop 传入 SVG 的 原始内容字符串。

基本用法

<template>
  <div>
    <!-- 基本用法 -->
    <SVGIcon :icon="mySvgIconString" />

    <!-- 通过 CSS class 控制大小和颜色 -->
    <SVGIcon :icon="anotherIconString" class="custom-icon" />

    <!-- 通过内联样式控制 -->
    <SVGIcon :icon="thirdIconString" style="font-size: 24px; color: blue;" />
  </div>
</template>

<script setup>
  import { ref } from 'vue';

  import { SVGIcon } from 'v-icon-svg';

  // 引入 SVG 图标字符串（构建工具 ?raw 后缀）
  import IconXXX from './assets/icon-xxx.svg?raw';

  // 假设这些变量包含了你的 SVG 图标的完整字符串内容
  const mySvgIconString = ref('<svg viewBox="0 0 1024 1024">...</svg>');
  const anotherIconString = ref('<svg>...</svg>');
  const thirdIconString = ref('<svg>...</svg>');
</script>

<style>
  .custom-icon {
    font-size: 32px; /* 控制图标大小 */
    color: red; /* 控制图标颜色 */
  }
</style>

渲染模式

运行时方案支持两种渲染模式：

1. Symbol + Use 模式（默认推荐）

<!-- 默认模式，使用 <symbol> + <use> 渲染 -->
<SVGIcon :icon="iconString" />

特点：

• ✅ 性能优化：相同 SVG 会被缓存为 symbol，多次使用时只存储一份
• ✅ 内存占用小：重复图标共享同一个 symbol 定义
• ✅ 渲染效率高：浏览器原生支持，渲染性能好
• ❌ 某些场景可能有兼容性问题（见下文）

2. Inline 模式

<!-- 内联模式，直接渲染完整的 SVG 内容 -->
<SVGIcon :icon="iconString" :inline="true" />

特点：

• ✅ 完整的 SVG 控制：可以对 SVG 内部元素进行精确的样式控制
• ✅ 避免 <use> 元素的兼容性问题
• ✅ 解决特殊场景问题：html2canvas、跨 iframe、某些导出工具等
• ❌ 内存占用较大：每次使用都渲染完整的 SVG 内容
• ❌ 性能相对较低：无法共享 symbol 定义

🎯 使用场景选择

| 场景 | 推荐模式 | 原因 | | ----------------------------- | ------------ | ---------------------------------------------- | | 常规图标显示 | Symbol + Use | 性能最优，内存占用小 | | html2canvas 截图 | Inline | <use> 在 html2canvas 中可能无法正确渲染 | | 跨 iframe 使用 | Inline | <use> 引用的 symbol 可能在 iframe 外无法访问 | | PDF 导出 | Inline | 某些 PDF 生成工具对 <use> 支持不好 | | 需要精确控制 SVG 内部样式 | Inline | 可以直接操作 SVG DOM 元素 | | 图标库、大量重复图标 | Symbol + Use | 充分利用缓存优势 |

🔧 html2canvas 场景示例

<template>
  <div ref="captureArea">
    <!-- ❌ html2canvas 可能无法正确处理 -->
    <SVGIcon :icon="iconString" />

    <!-- ✅ html2canvas 可以正确处理 -->
    <SVGIcon :icon="iconString" :inline="true" />
  </div>
</template>

<script setup>
  import html2canvas from 'html2canvas';

  const captureScreenshot = async () => {
    const canvas = await html2canvas(captureArea.value);
    // 使用 inline 模式的图标会被正确渲染到 canvas 中
  };
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | | ----------- | ------- | ------- | --------------------------------------------------------------- | | icon | String | - | 必需，包含 SVG 完整内容的字符串 | | colorless | Boolean | true | 是否自动处理 SVG 的颜色属性（fill、stroke），使其继承父元素颜色 | | inline | Boolean | false | 是否使用内联模式渲染 SVG |

核心特性

• 动态渲染：直接将 SVG 字符串传递给 icon prop 进行渲染
• CSS 控制：
  • 图标大小默认继承并跟随父元素的 font-size（因为组件内部设置了 width: 1em; height: 1em;）
  • 图标颜色默认继承父元素的 color（因为组件内部设置了 fill: currentColor;）
• 颜色处理：组件内部会自动处理 SVG 的 fill 和 stroke 属性，使其继承父元素的 color 属性
• 智能缓存：Symbol 和 Inline 模式分别维护缓存，避免数据冲突

重要约束： 为了确保图标正确渲染，请不要使用包含 <defs> 或 <clipPath> 标签的 SVG 字符串。

⚡ 构建时方案（Webpack/Rspack 插件）

提供了一个 Webpack/Rspack(Rsbuild) 插件，可以直接将 SVG 文件作为 Vue 组件导入使用，无需手动处理 SVG 内容。

需要安装 vue 版本对应的 @vue/compiler-sfc 对应版本

在 webpack.config.js 中配置

const { VueSvgIconPlugin } = require('v-icon-svg/plugin');

module.exports = {
  // ... 其他配置
  plugins: [
    // ... 其他插件
    new VueSvgIconPlugin({
      include: /src\/assets\/icons/, // 只处理特定目录的SVG
      rawQuery: 'raw',
      urlQuery: 'url',
      inlineQuery: 'inline',
    }),
  ],
};

import ArrowIcon from './arrow.svg'; // Vue 组件
import arrowSvg from './arrow.svg?raw'; // 原始字符串
import arrowUrl from './arrow.svg?url'; // 文件 URL
import arrowInline from './arrow.svg?inline'; // Base64 内联

注意: 配置 include 后，其他 svg rule 规则将忽略该插件所配置的 include 的资源。

配置选项

| 选项 | 类型 | 默认值 | 说明 | | ----------- | ------ | --------- | ----------------------------------------------------- | | test | RegExp | /\.svg$/ | 匹配要处理的文件 | | include | RegExp | null | 仅包含匹配的目录 | | exclude | RegExp | null | 排除匹配的目录 | | rawQuery | String | 'raw' | 当资源包含此 query 参数时，返回原始 SVG 字符串 | | urlQuery | String | 'url' | 当资源包含此 query 参数时，返回 SVG 文件 URL | | inlineQuery | String | 'inline' | 当资源包含此 query 参数时，返回 base64 编码的内联内容 |

在 Vue 组件中使用

<template>
  <div>
    <IconHome class="my-icon" />
    <IconMenu class="my-icon" />
  </div>
</template>

<script>
  // 直接导入SVG文件作为Vue组件
  import IconHome from '@/assets/icons/home.svg';
  import IconMenu from '@/assets/icons/menu.svg';

  export default {
    components: {
      IconMenu,
      IconHome,
    },
  };
</script>

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

构建时方案优势

1. 构建时处理：所有 SVG 处理在构建时完成，不影响运行时性能
2. 按需加载：每个 SVG 变成独立的 Vue 组件，支持代码分割
3. 缓存优化：构建结果可以被缓存，提高开发效率
4. 简化使用：直接导入 SVG 文件，更符合直觉的开发体验

📊 性能对比与最佳实践

方案选择指南

| 需求 | 推荐方案 | 理由 | | ------------------------ | -------------------------- | -------------------- | | 静态图标资源 | 构建时方案 | 性能最优，开发体验好 | | 第三方动态图标 | 运行时 Symbol 模式 | 平衡性能和灵活性 | | html2canvas/PDF 导出 | 运行时 Inline 模式 | 避免兼容性问题 | | 图标库应用 | 构建时方案 + 运行时 Symbol | 按需加载 + 缓存优化 |

性能基准

// 相同图标重复使用 100 次的场景
// Symbol 模式：1 个 symbol 定义 + 100 个 use 引用
// Inline 模式：100 个完整的 SVG 元素
// 构建时方案：编译时优化，运行时开销最小

最佳实践

1. 优先使用构建时方案处理静态图标资源
2. 运行时方案作为补充，处理动态或第三方图标
3. 根据具体场景选择渲染模式：
   • 常规场景：Symbol + Use
   • 特殊兼容性需求：Inline
4. 合理设置 colorless 属性，确保颜色继承符合预期

🛠️ 兼容性

• Vue: 2.7+ / 3.0+
• 构建工具: Webpack 5/ Rspack 1
• 浏览器: 现代浏览器（支持 SVG <symbol> 和 <use> 元素）

📦 构建产物

• 支持 Tree Shaking
• 提供 ESM/CJS 两种格式

dist/
  ├── esm/            # ES Module 格式
  ├── lib/            # CommonJS 格式