更新记录

1.0.0（2026-07-12）

• 发布 Android、iOS UTS 原生 Rive .riv 动画组件。
• 支持 uni-app App nvue 页面和 uni-app x App。
• 支持本地 /static 文件、本地绝对路径、content:// 地址和网络资源。
• 支持指定 Artboard、Animation、State Machine、缩放、对齐和循环模式。
• 支持播放、暂停、继续、停止、重置、清理和重新加载。
• 支持 State Machine 的 trigger、boolean、number 输入。
• 支持加载、就绪、播放、暂停、继续、停止、重置、输入、清理和错误事件。
• Android 原生操作和事件统一切换到主线程，兼容传统 uni-app nvue 的 ref 方法调用。
• Android 在标准基座缺少 Rive runtime 时返回 missing_runtime，避免应用崩溃。

平台兼容性

uni-app(3.8.0)

uni-app x(3.8.0)

kongbai-rive

kongbai-rive 是基于 UTS 原生组件开发的 Rive .riv 动画播放器，适用于 uni-app App nvue 页面和 uni-app x App。组件封装 Android、iOS 官方 Rive Runtime，支持本地和网络资源、普通动画、State Machine、播放控制、循环、缩放及对齐。

适合启动动画、空状态、按钮反馈、引导页、直播互动、角色动画等 App 场景。组件不包含广告代码，不采集、不存储、不上传用户个人信息。

平台支持

组件依赖原生 Rive SDK。安装或更新插件后，必须重新制作自定义基座或重新云打包，标准基座和热更新无法添加第三方 AAR、CocoaPods 及 native .so。

原生依赖

• Android：app.rive:rive-android:10.4.5
• Android 最低版本：API 23
• iOS：RiveRuntime 6.21.1
• iOS 最低版本：iOS 14

依赖已写入插件的 app-android/config.json 和 app-ios/config.json，制作基座或云打包时由 HBuilderX 自动下载。

安装和运行

1. 将插件放入项目的 uni_modules/kongbai-rive。
2. 将有效的 .riv 文件放入项目 static，例如 static/rive/demo.riv。
3. 重新制作自定义基座，选择自定义基座运行项目。

组件遵循 uni_modules 规范自动注册，不需要手动 import。

• 传统 uni-app 必须在 .nvue 页面中使用。
• uni-app x 在 .uvue 页面中使用。
• 示例中的 /static/rive/demo.riv 请替换为项目自己的有效 Rive 文件。

uni-app nvue 最简示例

<template>
  <view>
    <kongbai-rive
      ref="rive"
      class="rive-player"
      src="/static/rive/demo.riv"
      stateMachine="Designer's Test"
      :autoPlay="true"
      @ready="onReady"
      @error="onError"
    ></kongbai-rive>

    <text @click="pause">暂停</text>
    <text @click="resume">继续</text>
    <text @click="setExpert">切换 Expert</text>
  </view>
</template>

<script>
export default {
  methods: {
    pause() {
      this.$refs.rive.pause()
    },
    resume() {
      this.$refs.rive.resume()
    },
    setExpert() {
      this.$refs.rive.setNumber('Level', 2)
    },
    onReady() {
      console.log('Rive 加载完成')
    },
    onError(event) {
      const detail = event.detail || event
      console.log('Rive 加载失败', detail.dynamicJSONFields || detail)
    }
  }
}
</script>

<style>
.rive-player {
  width: 750rpx;
  height: 500rpx;
}
</style>

传统 nvue 直接通过组件 ref 调用公开方法，不要使用 $callMethod()，也不要将 ref 强制转换为普通 Vue 组件。

uni-app x 最简示例

<template>
  <view>
    <kongbai-rive
      ref="riveRef"
      class="rive-player"
      src="/static/rive/demo.riv"
      stateMachine="Designer's Test"
      :autoPlay="true"
      @ready="onReady"
      @error="onError"
    />
  </view>
</template>

<script setup lang="uts">
const riveRef = ref<KongbaiRiveElement | null>(null)

const pause = () => riveRef.value?.pause()
const resume = () => riveRef.value?.resume()
const setExpert = () => riveRef.value?.setNumber('Level', 2)
const onReady = () => console.log('Rive 加载完成')
const onError = () => console.log('Rive 加载失败')
</script>

<style lang="scss">
.rive-player {
  width: 750rpx;
  height: 500rpx;
}
</style>

加载资源

本地资源

推荐将文件放在项目 static/rive 目录，通过根路径加载：

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

也可以通过方法切换文件：

this.$refs.rive.load('/static/rive/demo.riv')

不要引用 unpackage 中的编译产物。插件会将 /static 路径转换为 App 运行时的真实文件地址。

网络资源

this.$refs.rive.load('https://example.com/demo.riv')

网络地址必须能被 App 直接访问。Android 的 content:// 地址和本地绝对路径也可以传给 load()。

普通动画和 State Machine

普通 Animation：

<kongbai-rive
  src="/static/rive/demo.riv"
  animation="Animation 1"
  loop="loop"
/>

State Machine：

<kongbai-rive
  ref="rive"
  src="/static/rive/demo.riv"
  stateMachine="Main State Machine"
/>

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

Artboard、Animation、State Machine 和输入名称必须与 Rive Editor 中完全一致。如果文件只有空时间轴，组件会正常加载但画面不会变化。

属性

fit

支持 contain、cover、fill、fitWidth、fitHeight、none、scaleDown。兼容下划线形式，例如 fit_width。

alignment

支持 center、top、bottom、left、right、topLeft、topRight、bottomLeft、bottomRight。兼容下划线形式，例如 top_left。

loop

方法

事件

Android 事件数据包含 src，错误事件额外包含 code 和 message。传统 nvue 可能将事件数据包装在 dynamicJSONFields 中。iOS 当前主要将事件作为状态通知使用，不保证携带与 Android 相同的详情。

Android 错误码

iOS 可能返回 empty_src、invalid_src、read_failed、parse_failed、load_failed 等错误状态。

常见问题

标准基座启动后崩溃或提示 missing_runtime

标准基座不包含 Rive Android AAR 和 native .so。请重新制作包含本插件的自定义基座，并在运行窗口选择该基座。仅重新编译页面或热更新无效。

nvue 提示 load is not a function

确认页面扩展名是 .nvue，插件位于 uni_modules/kongbai-rive，并且插件目录中没有同名普通 Vue 包装组件。更新插件后需要停止旧任务并重新编译。

ready 和 play 已触发，但画面不动

先确认 .riv 文件内存在真正有关键帧变化的 Animation 或有效 State Machine。部分文件虽然包含名为 Animation 1 的空时间轴，但前后画面完全相同。建议显式填写正确的 animation 或 stateMachine 名称。

点击方法没有反应

确认已经收到 ready。传统 nvue 直接调用 this.$refs.rive.play()，不要使用 $callMethod()。State Machine 输入名称必须与文件完全一致。

动画区域空白

必须给组件设置明确宽高，并确认资源路径可读。建议先使用已确认包含有效动画或 State Machine 的 .riv 文件排除资源问题。

相关文档

• UTS uni-app 兼容模式组件
• UTS 原生插件
• Rive 官方文档

技术支持 QQ：6864952