做直播礼物、入场特效、会员开通或活动奖励时，SVGA 往往不是“能播放就行”。真正麻烦的是连续礼物到来后画面闪一下、旧动画的回调跑到新动画上、资源还没加载完就被下一条覆盖；接完原生 SDK 后，又发现普通调试基座根本没有对应依赖。
如果项目是 uni-app App nvue 或 uni-app x App，kongbai-svga 就是为这些问题准备的原生 SVGA 播放组件。它基于 Android/iOS 原生 SVGAPlayer 封装，重点不是堆接口，而是把直播和业务动画的连续播放链路做完整。
一、先明确适用范围，少走弯路
组件支持 uni-app App nvue 页面和 uni-app x App 的 Android、iOS 端：Android 最低 API 21，iOS 最低 iOS 12。普通 uni-app vue 页面、H5 和小程序不在支持范围内。
这点很重要：组件依赖原生 SDK，导入或更新插件后必须重新制作自定义基座或重新云打包。普通调试基座和热更新不会包含 SVGAPlayer-Android，出现 NoClassDefFoundError: com.opensource.svgaplayer.SVGAImageView 时，优先检查打包方式，而不是反复改业务代码。
二、连续礼物为什么容易闪屏、串线
连续调用动画播放时，旧资源可能还在解析，新的礼物又已经到达。如果播放器没有处理好资源切换，常见现象就是闪屏、旧动画完成事件误触发、回调串到新礼物。
kongbai-svga 在再次调用 loadAndPlay() 时，会停止当前动画、清空画布并加载新资源；旧资源尚未完成的解析结果和播放回调会被忽略。对礼物流、连击特效这类“后来的动画优先”的场景，这比单纯包一层原生播放器更省心。
三、最小接入
插件放入 uni_modules/kongbai-svga 后会自动注册，无需手动 import。uni-app 项目在 .nvue 页面使用，uni-app x 项目在 .uvue 页面使用。
<kongbai-svga
ref="svgaRef"
class="svga-player"
:autoPlay="false"
:loops="1"
fillMode="forward"
scaleMode="fitCenter"
@ready="onReady"
@finished="onFinished"
@error="onError"
></kongbai-svga>
加载并播放本地资源：
this.$refs.svga.loadAndPlay('/static/gift-1.svga')
播放网络资源：
this.$refs.svga.loadAndPlay('https://example.com/gift-1.svga')
本地资源请放到 static 目录，通过 /static/... 根路径加载。网络地址必须能被 App 直接访问，加载失败会通过 error 事件返回原因。
四、播放控制不只是一句 play
组件支持 load、play、pause、resume、stop、clear，以及循环次数、结束画面与缩放模式控制。暂停会保留当前帧，resume 从暂停位置继续；stop 会重置播放进度；clear 会释放当前资源，后续需重新加载。
做仪式感动画时，指定帧能力也很实用：
this.$refs.svga.stepToFrame(30, true)
this.$refs.svga.stepToPercentage(0.5, true)
this.$refs.svga.playRange(20, 40, false)
资源触发 ready 后再执行跳帧，能够避免“资源未就绪就控制播放”的不确定行为。
五、适合哪些业务
1. 直播间礼物、连击和入场动画
2. 会员开通、勋章解锁、等级升级
3. 活动抽奖、任务完成、奖励到账
4. 需要内嵌音频、循环控制或指定帧播放的 App 特效
组件也提供 ready、play、loop、frame、finished、error 等事件，方便把动画状态接入自己的业务埋点、礼物队列或页面状态。
插件市场地址：
https://ext.dcloud.net.cn/plugin?id=28716
如果你的项目正卡在“SVGA 能播但不稳定”的阶段，可以先从连续资源切换和重新制作包含原生依赖的基座这两件事开始检查。
