更新记录

v0.1.9（2026-09-27） 下载此版本

优化预加载方案，使用indexedDB缓存替代内存缓存

v0.1.8（2026-08-28） 下载此版本

新增 svga 播放开始时的 start 函数

v0.1.7（2026-08-28） 下载此版本

修复 process 函数丢失

平台兼容性

uni-app(3.8.4)

一个使用 svga 库封装的 uniapp H5 SVGA 播放组件示例项目

预览

特性

• IndexedDB 持久缓存：资源字节缓存在 IndexedDB（磁盘级），跨会话复用，二次播放零网络请求
• 零开销预加载：preload 只下载字节写入 IndexedDB，不做解析、不挂载、不占运行时内存
• 按需解析、用完即还：play 每次直接读 IndexedDB 转 objectURL，再创建 Parser / Player；播完、停止或失败立即销毁并 revokeObjectURL——不保留任何会话级缓存，常驻内存恒定为单次播放的量
• 缓存过期：通过 cacheMaxAge 控制 IndexedDB 缓存有效期，过期自动重新下载
• 尺寸单位：width / height 支持 px、rpx、vw 等 CSS 单位（rpx 按 750 基准换算为 px）

平台限制：组件依赖 indexedDB、document.createElement('canvas')、URL.createObjectURL 等浏览器 API，仅支持 H5 平台。

安装依赖

pnpm install
# 或仅安装播放器依赖
pnpm install svga

基本使用

<script setup lang="ts">
import svgaPlayer from '@/components/svga-player/svga-player.vue'

const svgaPlayerRef = ref<InstanceType<typeof svgaPlayer>>()

const svgaUrl = new URL('@/static/svga/angel.svga', import.meta.url).href

onMounted(() => {
  svgaPlayerRef.value?.play(svgaUrl)
})
</script>

<template>
  <svga-player ref="svgaPlayerRef" />
</template>

完整示例

<script setup lang="ts">
import svgaPlayer from '@/components/svga-player/svga-player.vue'

const svgaPlayerRef = ref<InstanceType<typeof svgaPlayer>>()

const svga = [
  new URL('@/static/svga/angel.svga', import.meta.url).href,
  new URL('@/static/svga/rose.svga', import.meta.url).href,
]

const loop = ref(1)

onMounted(() => {
  svgaPlayerRef.value?.play(svga[0])
  svgaPlayerRef.value?.preload(svga[1])
})

async function handlePlay(url: string) {
  try {
    await svgaPlayerRef.value?.play(url)
  }
  catch (e) {
    // play 失败时除触发 error 事件外，Promise 也会 reject
    console.error('play failed:', e)
  }
}

function handleStop() {
  svgaPlayerRef.value?.stop()
}

function onReady() {
  console.info('SVGA ready')
}

function onStart() {
  console.info('SVGA started')
}

function onProcess(p: { elapsed: number, remain: number }) {
  console.info(`elapsed: ${p.elapsed}s, remain: ${p.remain}s`)
}

function onEnd() {
  console.info('SVGA playback ended')
}

function onError(e: unknown) {
  console.error('SVGA error:', e)
}

function onLoopChange(e: any) {
  loop.value = e.detail.value
}
</script>

<template>
  <view>
    <slider :value="loop" :min="1" :max="10" show-value @change="onLoopChange" />
    <button @click="handlePlay(svga[0])">天使</button>
    <button @click="handlePlay(svga[1])">玫瑰</button>
    <button @click="handleStop">停止</button>

    <svga-player
      ref="svgaPlayerRef"
      :loop="loop"
      canvas-id="svga-main"
      @ready="onReady"
      @start="onStart"
      @process="onProcess"
      @end="onEnd"
      @error="onError"
    />
  </view>
</template>

Props 属性

Method 实例方法

通过 ref 调用，均已 defineExpose 暴露。

Events 事件

工作流程

preload(url | urls)  ──→  fetch 字节  ──→  写入 IndexedDB（不解析 / 不挂载 / 不占运行时内存）
                                                │
play(url)  ──→  读 IndexedDB ── 命中未过期 ──→  Blob → createObjectURL（仅存活于本次播放）
           │                ── 命中已过期 ──→  删除旧记录 + 后台重下，本次用原 url
           │                 ── 未命中 ──→  用原 url，后台静默下载供下次使用
                                                ↓
                  Parser.load(url)  ──→  Player.mount(video)  ──→  start()
                   │
                   │  加载期间收到 stop() / unmount → 标记 cancelled，
                   │  play() 在检查点静默 cleanup() 退出
                   ↓
        onEnd() / stop() / 失败  ──→  cleanup(): stop + clear + destroy Parser/Player
                                                ──→  revokeObjectURL，释放内存
                                                ──→  之后才触发 @end（回调内可立即 play()）