概览（Overview）
欢迎在 Android 上使用 Rive。Rive 运行时库是开源的，Android 版本位于 rive-android 仓库。
Android 的两套 API
Android 目前有两套主要接入方式：
1) 新版 Compose API（Beta）
这套 API 为 Jetpack Compose 设计，采用更现代、声明式的 UI 模型。
- 入口：
RiveComposable - 特点：线程模型更强，稳定性和灵活性更高，可将 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 打开后：
- 选择
app配置与目标设备 - 在
Build -> Select Build Variant...中选择preview (default) - 其他变体用于开发，需要额外配置，见 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 的基本流程是：
- 创建 Worker（RiveWorker）
- 加载
.riv文件（RiveFileSource） - 在
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>：
LoadingSuccessError
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 / 数据绑定等，请继续阅读：
- Artboards：/docs/Runtimes/Artboards
- State Machines：/docs/Runtimes/State Machines
- Data Binding：/docs/Runtimes/Data Binding
启用日志（Logging）
Compose API 使用了较多日志（尤其 Debug 级别）帮助诊断问题。默认不输出，你可以设置全局 logger 到 Logcat：
RiveLog.logger = RiveLog.LogcatLogger()
可在 Activity.onCreate 或 Application 初始化早期设置。