更新记录

1.1.0（2026-08-13）

1、uni-app x增***eb和小程序平台的适配； 2、优化修复已知问题。

1.0.0（2026-08-13）

uniapp中，svg渲染支持全平台！uni-app X中，svg渲染支持鸿蒙、安卓、ios APP。

平台兼容性

uni-app(5.01)

uni-app x(4.31)

zmz-uts-svg

本人擅长ASCF、小程序、鸿蒙APP等开发，想合作的可以留言或者私聊！

跨端 SVG 渲染组件，UTS 标准模式。补齐 image 在 安卓/鸿蒙/IOS/ASCF/小程序等场景下的缺口。

• 支持 SVG 字符串、本地路径、static 资源、网络地址、data:image/svg+xml
• 缩放模式对齐 image 的 mode
• 符合 easycom，导入后无需 import、无需注册
• 最低 HBuilderX 4.31+（Harmony 建议 4.61+）

平台说明

插件市场详情页的「平台兼容性」以 package.json 为准。各端实现差异如下：

普通 uni-app 没有 UniNativeViewElement，不能直接使用 native-view。UTS Android / iOS 在非 UNI-APP-X 下为占位实现，仅保证模块可编译；App 端实际走 renderjs。

安装

1. 通过插件市场导入，或将 zmz-uts-svg 放到项目 uni_modules 目录。
2. 插件 components 符合 easycom，页面中直接写 <uni-svg> 即可。

uni_modules 规范 规定：插件目录不能携带 pages.json、manifest.json、App.vue / App.uvue。若工程同时存在 uni-svg.vue 与 uni-svg.uvue，uni-app-x 建议在项目 pages.json 中显式指向 .uvue（本示例工程已这样配置）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^uni-svg$": "@/uni_modules/zmz-uts-svg/components/uni-svg/uni-svg.uvue"
    }
  }
}

普通 uni-app 无需上述配置，autoscan 会使用 uni-svg.vue。

基本用法

以下示例与工程 pages/index/index 一致，覆盖三种常见 src。

uni-app-x（uvue）

<template>
  <view>
    <!-- SVG 字符串 -->
    <uni-svg :src="logoSvg" :width="120" :height="120" mode="aspectFit"
      @load="onLoad('string')" @error="onError"></uni-svg>

    <!-- 本地 static -->
    <uni-svg src="/static/svg-demo.svg" width="120px" height="120px" mode="aspectFit"
      @load="onLoad('local')" @error="onError"></uni-svg>

    <!-- 网络 SVG -->
    <uni-svg src="https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/1f30d.svg"
      :width="240" :height="240" mode="aspectFit"
      @load="onLoad('http')" @error="onError"></uni-svg>
  </view>
</template>

<script setup lang="uts">
  import { ref } from 'vue'

  const logoSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120">
    <rect width="120" height="120" rx="24" fill="#2563eb"/>
    <path d="M31 63l18 18 40-44" fill="none" stroke="#fff" stroke-width="12" stroke-linecap="round" stroke-linejoin="round"/>
  </svg>`

  const tip = ref('等待加载…')

  function onLoad(from : string) {
    tip.value = `load: ${from}`
  }

  function onError(e : UTSJSONObject) {
    const raw = e['errMsg']
    tip.value = `error: ${raw != null ? `${raw}` : 'unknown'}`
  }
</script>

普通 uni-app（vue）

<template>
  <uni-svg :width="120" :height="120" :src="logoSvg" mode="aspectFit" @load="onLoad" @error="onError" />
</template>

<script setup>
const logoSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120">
  <rect width="120" height="120" rx="24" fill="#2563eb"/>
  <path d="M31 63l18 18 40-44" fill="none" stroke="#fff" stroke-width="12" stroke-linecap="round" stroke-linejoin="round"/>
</svg>`

function onLoad() {}
function onError(e) {
  console.error(e)
}
</script>

也支持：

<uni-svg :width="240" :height="160" src="/static/svg-demo.svg" />
<uni-svg width="120px" height="120px" src="https://www.w3.org/Icons/SVG/svg-logo.svg" />
<uni-svg style="width: 120px; height: 120px;" :src="dataUrl" />

请为组件设置 width / height 属性，或通过外部样式指定宽高。

属性

事件

error.errMsg 常见值：

方法

通过 ref 获取组件实例后调用。

<uni-svg ref="svgRef" :src="logoSvg" :width="120" :height="120"></uni-svg>

// uni-app / Options API
this.$refs.svgRef.setSrc(newSrc)
this.$refs.svgRef.reload()
this.$refs.svgRef.clear()

// uni-app-x script setup
const svgRef = ref(null)
svgRef.value!.setSrc(newSrc)

注意事项

1. 必须使用自定义调试基座（App-iOS / Windows） 本插件含原生 UTS（utssdk/app-ios）。官方说明：Windows 或未安装 Xcode 的 Mac 必须云打自定义调试基座。标准基座没有 SvgViewByJs，会报 undefined class: UTSSDKModulesSvgSvgViewByJs。 修改 utssdk 原生代码后，需重新制作自定义基座。

2. 网络 SVG 权限 Android 插件已声明 INTERNET。Harmony / iOS 访问网络 SVG 时，请在项目 manifest.json 中按平台补齐网络相关配置（插件目录不能携带 manifest.json）。

3. Android 依赖 uni-app-x 使用 com.caverock:androidsvg:1.4（JAR，与运行时一致）。不要再把 androidsvg-aar 放到 libs，会与云打包自带的 JAR 冲突。Android 最低 API 21。

4. 宽高 组件默认 width / height 为空。未设置时依赖外部样式或父容器；建议始终显式指定，避免部分端高度为 0。

5. Gradle 无法执行 若 HBuilderX 提示 Gradle 不是可执行程序：在 设置 → 运行配置 → Android Gradle 中指定本机解压后的 gradle.bat（例如 ...\gradle-8.x\bin\gradle.bat），不要指向 .gradle\wrapper\dists\... 缓存路径。Gradle 建议 7.5–8.9.x。

常见问题

Q：运行 iOS 报 undefined class: ...SvgViewByJs？ A：当前用的是标准基座。请云打包「自定义调试基座」，运行时选择 使用自定义基座运行。

Q：本地 SVG 不显示？ A：路径需相对项目，推荐 /static/xxx.svg（与示例页一致）。确认文件确为 SVG 文本（以 <svg 或 <?xml 开头）。

Q：网络 SVG 在 Android 能显示、iOS 不能？ A：iOS uni-app-x 走逻辑层请求后再交给 WKWebView；请确认自定义基座、ATS / 网络权限，以及地址返回的是 SVG 文本而非 HTML。

目录结构

uni_modules/zmz-uts-svg/
├── components/uni-svg/uni-svg.vue     # 普通 uni-app easycom（renderjs）
├── components/uni-svg/uni-svg.uvue    # uni-app-x（native-view）
├── utssdk/
│   ├── interface.uts
│   ├── app-android/                   # UNI-APP-X: AndroidSVG；否则占位
│   ├── app-ios/                       # UNI-APP-X: WKWebView；否则占位
│   ├── app-harmony/                   # native-view + ArkUI Image
│   ├── app-js/
│   └── web/
├── static/demo.svg
├── index.uts
├── package.json
├── changelog.md
└── readme.md

参考

• uni_modules 规范
• 制作和发布插件指南
• UTS 标准模式组件
• native-view
• UTS 插件