跳到主要内容

概览（Overview）

欢迎在 Android 上使用 Rive。Rive 运行时库是开源的，Android 版本位于 rive-android 仓库。

Android 的两套 API​

Android 目前有两套主要接入方式：

1) 新版 Compose API（Beta）​

这套 API 为 Jetpack Compose 设计，采用更现代、声明式的 UI 模型。

  • 入口：Rive Composable
  • 特点：线程模型更强，稳定性和灵活性更高，可将 Rive 工作分配到多线程
  • 建议：新项目优先使用；旧项目建议在合适时机迁移

2) 旧版 View API（Legacy）​

基于 Android View + XML 的成熟方案。

  • 入口：RiveAnimationView
  • 可用于 XML 布局或代码创建
  • 也可在 Compose 中通过 AndroidView 使用

说明：之所以称为 Legacy，是因为后续研发重点在 Compose API 上；Legacy 仍会维护，但未来会逐步收敛新特性支持。

示例应用（Sample App）​

可通过官方示例应用体验 API 能力：

git clone https://github.com/rive-app/rive-android

在 Android Studio 打开后：

  1. 选择 app 配置与目标设备
  2. 在 Build -> Select Build Variant... 中选择 preview (default)
  3. 其他变体用于开发，需要额外配置，见 CONTRIBUTING.md

开始接入（Getting Started）​

如果你正在使用 Legacy API，请先看：

步骤 1：添加依赖​

建议使用最新版（见 Maven Central）：

dependencies {
    ...
    implementation 'app.rive:rive-android:<Latest Version>'
    // 可选：用于初始化
    implementation "androidx.startup:startup-runtime:1.1.1"
}

步骤 2：初始化 Rive​

Rive 需要初始化 C++ 运行时绑定。可选方式：

方式 A：通过 AndroidX Startup 自动初始化（推荐）​

<manifest ...>
  <application ...>
    <provider
      android:name="androidx.startup.InitializationProvider"
      android:authorities="${applicationId}.androidx-startup"
      android:exported="false"
      tools:node="merge">
        <meta-data android:name="app.rive.runtime.kotlin.RiveInitializer"
          android:value="androidx.startup" />
    </provider>
  </application>
</manifest>

方式 B：代码中调用初始化组件​

AppInitializer.getInstance(applicationContext)
  .initializeComponent(RiveInitializer::class.java)

方式 C：手动初始化（更灵活）​

Rive.init(context)

请确保在使用任何 Rive 功能前调用初始化。

步骤 3：在 Compose 中使用 Rive​

Compose API 的基本流程是：

  1. 创建 Worker（RiveWorker）
  2. 加载 .riv 文件（RiveFileSource）
  3. 在 Rive(...) Composable 中显示

3.1 创建 Worker​

setContent {
    // 简单方式
    val riveWorker = rememberRiveWorker()

    // 安全方式（可处理创建失败）
    val errorState = remember { mutableStateOf<Throwable?>(null) }
    val riveWorker = rememberRiveWorkerOrNull(errorState)
    if (riveWorker == null) {
        return@setContent
    }
}

3.2 加载 Rive 文件​

setContent {
  ... // riveWorker

  val riveFile = rememberRiveFile(
      RiveFileSource.RawRes.from(R.raw.my_rive_file),
      riveWorker
  )
}

rememberRiveFile 返回 Result<RiveFile>：

  • Loading
  • Success
  • Error
when (riveFile) {
    is Result.Loading -> LoadingIndicator()
    is Result.Error -> /* 处理错误 */
    is Result.Success -> {
        val file = riveFile.value
        // 继续使用 file
    }
}

3.3 显示 Rive​

when (riveFile) {
    is Result.Success -> {
        Rive(riveFile.value)
    }
    else -> {}
}

如需指定 Artboard / State Machine / 数据绑定等，请继续阅读：

启用日志（Logging）​

Compose API 使用了较多日志（尤其 Debug 级别）帮助诊断问题。默认不输出，你可以设置全局 logger 到 Logcat：

RiveLog.logger = RiveLog.LogcatLogger()

可在 Activity.onCreate 或 Application 初始化早期设置。

资源（Resources）​