更新记录

1.0.0（2026-02-27）

• 首次发布 hans-rive。
• 支持 uni-app x 的 App-Android 与 App-iOS。
• 提供基础配置：src、autoPlay、loop、artboardName、animationName、stateMachineName、debug。
• 提供实例方法：play()、pause()、stop()、reset()。
• 提供事件：ready、play、pause、stop、error(message)。

平台兼容性

uni-app x(4.87)

hans-rive

hans-rive 是一个 uni-app x 原生 Rive 组件，支持 App-Android、App-iOS。

使用文档

平台支持

• uni-app x / app-android: √
• uni-app x / app-ios: √
• uni-app x / app-harmony: -
• 其他平台：-

安装

• 在 HBuilderX 插件市场搜索 hans-rive，选择并导入到当前项目。
• 导入后插件会自动安装到项目的 uni_modules/hans-rive 目录。
• 组件可直接使用：<hans-rive />。

快速开始

<template>
  <hans-rive
    ref="riveRef"
    style="width: 240px; height: 240px;"
    src="/static/animations/demo.riv"
    :autoPlay="true"
    :loop="true"
    :debug="false"
    @ready="onReady"
    @error="onError"
  />
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { HansRiveInstance } from '@/uni_modules/hans-rive'

const riveRef = ref(null as HansRiveInstance | null)

function onReady() {
  riveRef.value?.play()
}

function onError(message: string) {
  console.error('[hans-rive]', message)
}
</script>

Props

• src: string：Rive 文件路径。建议使用 /static/... 本地资源路径。
• autoPlay?: boolean：是否自动播放。默认 true。
• loop?: boolean：是否循环播放。默认 true。
• artboardName?: string：可选，指定 Artboard 名称。
• animationName?: string：可选，指定 Animation 名称。
• stateMachineName?: string：可选，指定 StateMachine 名称。
• debug?: boolean：是否开启调试日志。默认 false。
• command?: string：命令式控制，支持 play | pause | stop | reset。
• commandVersion?: number：命令版本号。每次下发新命令时递增，触发 command 执行。
• width?: string | number：组件宽度（如 240、240px、100%）。
• height?: string | number：组件高度（如 240、240px、100%）。

Methods（通过 ref 调用）

• play()：播放。
• pause()：暂停。
• stop()：停止。
• reset()：重置到初始状态。

Events

• ready：原生视图初始化完成。
• play：调用播放后触发。
• pause：调用暂停后触发。
• stop：调用停止后触发。
• error(message: string)：初始化或配置更新异常。

注意事项

• src 仅支持项目内可访问的本地资源（推荐放在 static/ 目录）。
• 使用 command 时需要同步递增 commandVersion，否则不会重复触发同一命令。