更新记录

1.0.0（2026-07-24） 下载此版本

• 发布正式版本
• H5 统一使用 Data URI 图片渲染 SVG，避免原始 SVG 注入页面 DOM

平台兼容性

uni-app(3.8.0)

其他

aw-svg

在 uni-app 项目里渲染 SVG，不用配构建工具，也不用转字体图标。

支持三种输入方式：SVG 字符串、图片路径、标准化的 icon 数据。可以单色换色、多色换色，也能跟着你的主题变量走。

哪几个平台能用

• uni-app Vue2 / Vue3
• H5
• App-Vue
• 微信 / 支付宝 / QQ / 字节跳动小程序

先记住这 3 条

• 想最快跑通：用 svg 或 src
• 长期维护的图标：用 icon + colors + strict
• 在按钮、导航栏这些关键位置，建议加个 fallbackText

一、快速上手

先能看见图标再说。

1. 传一段 SVG 字符串

<aw-svg :svg="searchSvg" color="var(--aw-text-secondary, #6b7280)" :size="18" />

手头有 SVG 文本，或者接口返回的就是 SVG，直接贴进来就行。

2. 传本地路径或远程地址

<!-- 本地 -->
<aw-svg src="/static/demo/aw-svg-demo.svg" :size="32" />

<!-- 远程，如果要改色就带上 color 和 themeVars -->
<aw-svg :src="remoteSvgSrc" color="var(--aw-color-primary, #6366f1)" :themeVars="currentThemeVars" :size="32" />

<!-- 多色远程 SVG 也可以按颜色顺序传数组 -->
<aw-svg
  :src="remoteSvgSrc"
  :colors="[
    'var(--aw-color-warning, #f59e0b)',
    'var(--aw-text-primary, #1f2937)'
  ]"
  :themeVars="currentThemeVars"
  :size="32"
/>

src 适合展示型图标或静态资源。

3. 单色图标直接给 color

<aw-svg :svg="searchSvg" color="#333" :size="18" />

size 传数字或字符串都行，18 和 '18px' 效果一样。

二、正规用法

项目内的功能图标建议按这种方式来。后期换主题、改颜色都很稳。

1. 用 iconData

<aw-svg
  :icon="{
    viewBox: '0 0 24 24',
    nodes: [
      { tag: 'path', attrs: { d: 'M4 12h16', stroke: 'slot:primary', 'stroke-width': '2', fill: 'none' } },
      { tag: 'path', attrs: { d: 'M12 4v16', stroke: 'slot:primary', 'stroke-width': '2', fill: 'none' } }
    ]
  }"
  :colors="{ primary: '#111827' }"
  mode="strict"
  :size="20"
/>

iconData 结构比 SVG 字符串更规范，跨端表现也最好。

2. 颜色用命名槽位

<aw-svg
  :icon="settingsIcon"
  :colors="{ primary: '#111827', accent: '#3b82f6' }"
  mode="strict"
  :size="24"
/>

这么说吧：哪怕以后项目要切主题色，你只需要改 colors 里对应的 key 就行，不用到 SVG 里逐个找颜色。

3. 跟着主题变量走

<aw-svg
  :icon="settingsIcon"
  :colors="{ primary: 'var(--aw-text-muted, #9ca3af)' }"
  :themeVars="currentThemeVars"
  mode="strict"
  :size="20"
  fallbackText="⚙️"
/>

导航栏、工具栏、列表操作区都适合这么用。

4. 多色也能跟主题

<aw-svg
  :svg="themeBadgeSvg"
  :colors="{
    primary: 'var(--aw-color-primary, #6366f1)',
    secondary: 'var(--aw-color-secondary, #ec4899)',
    surface: 'var(--aw-text-inverse, #ffffff)'
  }"
  :themeVars="currentThemeVars"
  mode="strict"
  :size="24"
/>

品牌徽章、状态章、多层图标，只要想一键换色，都可以这么搞。

5. 最推荐的一组搭配

<aw-svg
  :icon="iconData"
  :colors="{ primary: 'var(--aw-color-primary, #6366f1)' }"
  :themeVars="currentThemeVars"
  mode="strict"
  :size="20"
  fallbackText="★"
/>

这套组合 icon + colors + themeVars + strict + fallbackText 基本覆盖了绝大多数场景，建议当模板用。

三、进阶用法

1. 传颜色数组替换多色

<aw-svg :svg="badgeSvg" :colors="['#111827', '#3b82f6', '#ffffff']" :size="24" />

按 SVG 内颜色出现的顺序替换。快速预览时很方便，但长期维护不如命名槽位清晰。

2. 两种槽位写法

在原始 SVG 里：

<path data-aw-slot="primary" fill="#000" d="..." />

在 iconData 里：

{
  tag: 'path',
  attrs: {
    d: 'M4 12h16',
    stroke: 'slot:primary',
    'stroke-width': '2',
    fill: 'none',
  },
}

原始 SVG 推荐用 data-aw-slot，iconData 推荐用 fill / stroke = 'slot:xxx'。

3. 常用进阶属性

<aw-svg
  :svg="loadingSvg"
  color="#3b82f6"
  :size="20"
  :strokeWidth="2"
  :spin="1.6"
  fallbackText="·"
/>

spin 传一个数字就是旋转一圈的秒数，传负数就是反转。

4. 调试诊断

<aw-svg
  :icon="iconData"
  :colors="{ primary: '#333' }"
  debug
  @diagnostic="onDiagnostic"
/>

打开后能看到当前用的什么渲染策略、iconData 校验过没过、加载失败了是在哪个环节。

5. 持久化缓存

如果远程 src 地址是固定的，可以开启持久化缓存，减少重复请求：

<aw-svg
  :src="remoteSvgSrc"
  color="var(--aw-color-primary, #6366f1)"
  :themeVars="currentThemeVars"
  :size="32"
  persistentCache
  :persistentCacheTtl="24 * 60 * 60 * 1000"
/>

默认关闭。缓存的是 src 对应的 SVG 文本，persistentCacheTtl 传毫秒数，0 表示不过期。缓存总体积默认限制在 600KB 以内，超出时会自动淘汰最久没用到的那条。

6. 预处理工具

如果你有一批 SVG 文件需要批量转成 iconData 格式，可以用这个脚本：

# 基本用法：单个文件转成 slot 格式的 iconData
node ./uni_modules/aw-svg/tools/optional-transform.js input.svg --pretty

# 输出结构化 nodes（适合 icon prop 直接使用）
node ./uni_modules/aw-svg/tools/optional-transform.js input.svg --format nodes --pretty

# 输出优化报告，开启精简压缩
node ./uni_modules/aw-svg/tools/optional-transform.js input.svg --format report --minify --pretty

# 批量处理目录下所有 SVG
node ./uni_modules/aw-svg/tools/optional-transform.js --dir ./svgs/ --out-dir ./output/ --format nodes --minify

# 指定多个文件
node ./uni_modules/aw-svg/tools/optional-transform.js a.svg b.svg c.svg --out-dir ./output/

参数说明：

脚本在 uni_modules/aw-svg/tools/ 目录下。它是 Node.js 脚本，不是前端模块，不会影响你项目的运行时包大小。

输出位置建议

输出的 JSON 文件不要放 static/ 目录。static/ 里的文件只能通过 URL 访问，不能 import。建议放到 common/svg-icons/ 或 assets/icon-data/ 这类目录下，方便在组件中直接导入。

原始 SVG 文件（.svg）也不要放 static/，否则会被打包进构建产物。建议在项目根目录单独建一个目录存放，比如 svg-source/，uni-app 不会打包它：

项目目录/
├── svg-source/           # 原始 SVG，不会被打包
│   ├── search.svg
│   └── settings.svg
├── common/svg-icons/     # 转出来的 JSON，通过 import 使用
│   ├── search.json
│   └── settings.json
└── static/               # 运行时需要通过 URL 访问的资源

处理命令：

node ./uni_modules/aw-svg/tools/optional-transform.js --dir svg-source --out-dir common/svg-icons --format nodes --minify --pretty

在组件中使用

<template>
  <aw-svg :icon="searchIcon.iconData" :colors="{ primary: '#333' }" mode="strict" />
</template>

<script>
import searchIcon from '@/common/svg-icons/search.json'

export default {
  data() {
    return {
      searchIcon,
    }
  },
}
</script>

模式说明

项目里长期维护的图标建议用 strict。

输入方式怎么选

优先顺序：icon → svg → src

• icon 最稳定，跨端和主题联动效果最好
• svg 方便快速接入
• src 适合直接展示，但要改色的话取决于运行环境能不能把资源读成文本

Props 一览

Events

iconData 结构

写法一：直接包一段 SVG

{
  svg: '<svg viewBox="0 0 24 24"><path d="..." /></svg>'
}

写法二：结构化节点

{
  viewBox: '0 0 24 24',
  nodes: [
    {
      tag: 'path',
      attrs: {
        d: 'M4 12h16',
        stroke: 'slot:primary',
        'stroke-width': '2',
        fill: 'none',
      },
    },
  ],
}

推荐使用的 tag：svg、g、path、circle、rect、line、polyline、polygon、ellipse

常见问题

图标出不来？

1. 先确认传的 SVG 或 iconData 本身是不是对的
2. 再看 strict 模式下的槽位名有没有匹配上
3. 确认主题变量有传进去
4. 最后看 diagnostic 输出，它会告诉你走到哪一步了

为什么 src 能显示但不能改色？

因为用 src 的时候，改不改色取决于运行环境能不能把这张图片读成 SVG 文本。关键位置的图标建议改用 svg 或 icon。

什么时候该加 fallbackText？

导航栏图标、按钮图标、列表操作图标等你需要保底显示的，正常情况不加也没事。