Rive 动画在 uni-app 里只显示不交互？把 State Machine 跑起来

Rive 的价值不只是“播放一个 .riv 文件”，而是让按钮、角色、进度、引导页能随着用户操作实时变化。可是在 uni-app 项目里，很多人会遇到同一类问题：文件能加载，画面却不动；点击后没有反馈；State Machine 配了却像没生效；甚至标准调试基座里直接缺少原生运行时。

kongbai-rive 是一个面向 uni-app App nvue 与 uni-app x App 的 UTS 原生 Rive 组件。它封装 Android/iOS 官方 Rive Runtime，把普通 Animation 和 State Machine 的播放、输入控制和事件统一到组件 API 中，适合做真正可交互的 App 动画。

一、为什么“能显示”不等于“能交互”

Rive 文件里可以包含 Artboard、Animation 和 State Machine。普通动画只需播放时间轴；交互效果则依赖 State Machine 的输入，例如 trigger、boolean 和 number。

最常见的坑是名称不匹配。Artboard、Animation、State Machine 以及输入名称必须和 Rive Editor 中完全一致。文件即使能正常加载，只要名称写错，画面也可能静止不动。

例如，页面配置 State Machine：

<kongbai-rive
ref="riveRef"
class="rive-player"
src="/static/rive/demo.riv"
stateMachine="Main State Machine"
:autoPlay="true"
@ready="onReady"
@error="onError"
/>

然后在业务逻辑中驱动交互：

this.$refs.rive.fire('submit')
this.$refs.rive.setBoolean('active', true)
this.$refs.rive.setNumber('progress', 50)

这三个方法分别对应 State Machine 的 trigger、boolean 和 number 输入。登录按钮反馈、角色表情切换、进度状态和新手引导，都可以交给 Rive 文件中的状态机处理。

二、先确认运行环境，避免白调半天

组件支持 uni-app App 的 nvue 页面，以及 uni-app x App 的 .uvue 页面；Android 最低 API 23，iOS 最低 iOS 14。普通 uni-app vue 页面、H5 与小程序不支持。

Rive Runtime 是原生依赖。安装或更新插件后，必须重新制作自定义基座或重新云打包，标准基座与热更新无法加入第三方 AAR、CocoaPods 和 native .so。Android 标准基座缺少运行时时，组件会返回 missing_runtime 错误，避免直接崩溃。

所以遇到“代码没报错但组件无法运行”，先检查是否正在使用包含插件的自定义基座，而不是先怀疑 State Machine 写错。

三、接入方式和资源加载

把插件放到 uni_modules/kongbai-rive 后会自动注册，不需要手动 import。传统 uni-app 必须在 .nvue 页面使用，uni-app x 则放到 .uvue 页面。

建议把 .riv 文件放在 static/rive 目录：

<kongbai-rive src="/static/rive/demo.riv" />

也可以按业务切换资源：

this.$refs.rive.load('/static/rive/level-up.riv')
this.$refs.rive.load('https://example.com/level-up.riv')

网络资源需要由 App 直接访问；Android 还支持传入 content:// 地址和本地绝对路径。不要直接引用 unpackage 中的编译产物，组件会自动处理 /static 路径到 App 运行时资源的转换。

四、动画控制别只停在 play

组件提供 play、pause、resume、stop、resetAnimation、clear 和 reload 等方法。暂停会保留当前画面，resume 从当前位置继续；重置适合重复触发的成功动画或错误反馈。

缩放和布局也可通过 fit、alignment 控制：

<kongbai-rive
src="/static/rive/demo.riv"
fit="contain"
alignment="center"
loop="oneShot"
/>

loop 支持 auto、loop、oneShot 和 pingPong。这样可以按动画本身的设计播放，也可以由页面统一约束播放次数。

五、适用场景

1. 启动页、空状态和引导页
2. 带点击反馈的按钮、表单和加载状态
3. 角色动画、直播互动和会员等级效果
4. 需要用 State Machine 驱动复杂 UI 状态的 App 动画

如果你已经在 Rive Editor 做好了交互动画，真正要解决的不是“怎么把文件塞进页面”，而是如何稳定地把状态机输入接到 App 业务事件上。kongbai-rive 提供的正是这层原生运行时与业务调用之间的桥梁。

插件市场地址：
https://ext.dcloud.net.cn/plugin?id=28717