更新记录

1.1.0（2026-09-05）

• 单独使用：自包含组件，import 后直接用
• 多色 SVG 图标：保留 path 自带 fill 颜色
• 换色：通过 color prop 动态修改单色图标颜色
• 渐变色：支持 linear / radial 渐变，自定义方向和色标
• URI 和 Base64：小程序/APP 端支持两种 data URI 编码格式
• spin 动画：CSS 旋转动画，可自定义周期
• rpx 尺寸：size prop 支持数字 / px / rpx / 百分比
• 圆角：radius prop 支持数字（px）和字符串（百分比）
• 缓存机制：三层 LRU 缓存（iconDef / svgHtml / dataUri），提升重复渲染性能
• iconfont 字体库：通过 unicode + fontFamily 渲染字体图标
• uni-icons 字体图标：内置 DCloud uni-icons 字体映射表，调用 addUniIconsFont() 注册后，可直接用 name 渲染（无需 <uni-icons> 组件，避免 easycom 注册问题和 Vue3 警告）
• 自定义字体图标：通过 addFontIcons(fontFamily, map) 注册任意 iconfont 字体映射表
• 自定义图标：支持 icon prop 内联传入、addIcons() 运行时注册、Vue.use() 插件模式
• 事件：支持 click / load / error 事件

平台兼容性

uni-app(5.0)

ux-svg-icon 跨平台 SVG 图标组件

跨平台 SVG 图标组件，支持多色图标、换色、渐变色、URI/Base64 格式、spin 动画、rpx 尺寸、圆角、缓存机制、iconfont 字体库、uni-icons 字体映射，兼容 H5 / APP / 小程序，Vue2 / Vue3 双版本支持。

平台兼容性

功能特性

• 单独使用：自包含组件，import 后直接用
• 多色 SVG 图标：保留 path 自带 fill 颜色
• 换色：通过 color prop 动态修改单色图标颜色
• 渐变色：支持 linear / radial 渐变，自定义方向和色标
• URI 和 Base64：小程序/APP 端支持两种 data URI 编码格式
• spin 动画：CSS 旋转动画，可自定义周期
• rpx 尺寸：size prop 支持数字 / px / rpx / 百分比
• 圆角：radius prop 支持数字（px）和字符串（百分比）
• 缓存机制：三层 LRU 缓存（iconDef / svgHtml / dataUri），提升重复渲染性能
• iconfont 字体库：通过 unicode + fontFamily 渲染字体图标
• uni-icons 字体图标：内置 DCloud uni-icons 字体映射表，调用 addUniIconsFont() 注册后，可直接用 name 渲染（无需 <uni-icons> 组件，避免 easycom 注册问题和 Vue3 警告）
• 自定义字体图标：通过 addFontIcons(fontFamily, map) 注册任意 iconfont 字体映射表
• 自定义图标：支持 icon prop 内联传入、addIcons() 运行时注册、Vue.use() 插件模式
• 事件：支持 click / load / error 事件

快速使用

<template>
  <!-- 基本用法 -->
  <ux-svg-icon name="back" :size="24" color="#fff" />

  <!-- rpx 尺寸 -->
  <ux-svg-icon name="flash" size="48rpx" color="#FFD54F" />

  <!-- 渐变色 -->
  <ux-svg-icon name="check" :color="{
    type: 'linear',
    direction: 'to right',
    stops: [
      { offset: '0%', color: '#FF6B6B' },
      { offset: '100%', color: '#4ECDC4' }
    ]
  }" :size="32" />

  <!-- spin 动画 -->
  <ux-svg-icon name="loading" :spin="true" :spin-duration="0.8" :size="24" color="#4fc3f7" />

  <!-- 圆角 -->
  <ux-svg-icon name="back" :radius="8" :size="40" />

  <!-- 内联传入完整 SVG -->
  <ux-svg-icon icon="<svg viewBox='0 0 24 24'><path d='M12 2L2 22h20L12 2z'/></svg>" :size="32" />

  <!-- iconfont 字体图标（直接传 unicode） -->
  <ux-svg-icon type="iconfont" unicode="&#xe600;" font-family="iconfont" :size="24" color="#333" />

  <!-- uni-icons 字体图标（addUniIconsFont 注册后，直接用 name） -->
  <ux-svg-icon type="iconfont" font-family="uniicons" name="contact" :size="24" color="#fff" />
</template>

<script>
import UxSvgIcon from '@/uni_modules/ux-svg-icon/components/ux-svg-icon/ux-svg-icon.vue'
import { addUniIconsFont } from '@/uni_modules/ux-svg-icon/components/ux-svg-icon/uni-icons-font.js'

// 注册 uni-icons 字体映射表，注册后可用 name 渲染
// 同时需在 App.vue 全局 @font-face 引入 uni.ttf 字体文件（见下方"字体图标使用"）
addUniIconsFont()

export default {
  components: { UxSvgIcon },
}
</script>

Props

渐变色配置

{
  type: 'linear',        // 'linear' 或 'radial'
  direction: 'to right', // 方向（见下表），仅 linear
  stops: [               // 色标数组
    { offset: '0%', color: '#FF6B6B' },
    { offset: '100%', color: '#4ECDC4', opacity: 0.8 }
  ]
}

Events

内置图标

自定义图标

方式1：addIcons 运行时注册

import UxSvgIcon from '@/uni_modules/ux-svg-icon/components/ux-svg-icon/ux-svg-icon.vue'

UxSvgIcon.addIcons({
  'my-icon': {
    content: '<path d="M12 2L2 22h20L12 2z"/>',
    fill: true,
    viewBox: '0 0 24 24',
  }
})
// 然后使用 <ux-svg-icon name="my-icon" />

方式2：icon prop 内联传入

<!-- 对象形式 -->
<ux-svg-icon :icon="{ content: '<path d=.../>', fill: true, viewBox: '0 0 24 24' }" />

<!-- 纯 SVG content 字符串 -->
<ux-svg-icon icon="<path d='M12 2L2 22h20L12 2z'/>" />

<!-- 完整 SVG 标签（自动提取 viewBox + 检测多色） -->
<ux-svg-icon icon="<svg viewBox='0 0 24 24'><path fill='#FF6B6B' d='...'/></svg>" />

方式3：Vue.use 插件模式

import UxSvgIcon from '@/uni_modules/ux-svg-icon/components/ux-svg-icon/ux-svg-icon.vue'

Vue.use(UxSvgIcon, {
  icons: {
    'my-icon': { content: '<path d=.../>', fill: true }
  }
})
// 全局注册组件 + 图标，直接使用 <ux-svg-icon name="my-icon" />

方式4：svgToIcon 工具函数

import { svgToIcon } from '@/uni_modules/ux-svg-icon/components/ux-svg-icon/icons.js'

// 完整 SVG 字符串 → 图标定义对象（自动提取 viewBox/content/检测多色/判断 fill）
const iconDef = svgToIcon('<svg viewBox="0 0 24 24"><path d="..."/></svg>')

缓存机制

三层 LRU 缓存提升重复渲染性能：

• addIcons() 覆盖图标时自动清空缓存
• UxSvgIcon.clearCache() 手动清空全部缓存

目录结构

uni_modules/ux-svg-icon/
├── components/ux-svg-icon/
│   ├── ux-svg-icon.vue    # 组件主体
│   ├── icons.js            # 图标定义 + addIcons + svgToIcon
│   ├── flash-off.js        # flash-off 图标路径数据
│   ├── svg-to-icon.js      # SVG 转 JS 对象工具
│   └── cache.js            # LRU 缓存工具
├── package.json
├── changelog.md
└── readme.md