概述
欢迎在 Android 上使用 Rive。Rive 运行时库是开源的，Android 版本可在 rive-android GitHub 仓库中找到。
两种 Android API
Rive for Android 提供了两个主要 API 用于将 Rive 集成到你的应用程序中。
新的 Compose API（Beta）
此 API 专为 Jetpack Compose 设计，允许采用更现代、声明式的方式构建 UI。它目前处于 Beta 阶段，正在接受额外测试，开发过程中可能会发现一些问题。我们会迅速解决这些问题。该 API 功能完整、可用于生产环境，推荐用于所有使用 Compose 的新项目，现有项目应在可行时迁移。
此 API 的入口点是 Rive 可组合函数，可以直接在 Compose UI 代码中使用。
除了提供更符合 Compose 习惯的体验外，该 API 还采用了更强的线程模型，具有更高的稳定性和灵活性，可以将 Rive 工作分散到多个线程上。
未来，这个线程模型还将包含一个基于 View 的 API，用于无法使用 Compose 的项目。
旧的基于 View 的 API
此 API 基于 Android View 和 XML 布局。它已广 泛应用于生产应用程序。它也支持 通过 AndroidView 使用 Compose，但需要一定的样板代码来设置。
此 API 的入口点是 RiveAnimationView，可以添加到 XML 布局或以编程方式实例化。
我们称之为"旧版" API，因为我们未来将重点开发新的 Compose API，但此 API 将继续得到一段时间的支持和维护。对于所有新的开发项目，我们推荐使用新的 Compose API。此外，建议在可行时迁移现有项目到新 API，因为旧版将来会被弃用，将只有有限或没有新功能开发。
示例应用
要探索 Android API，你可以运行我们的 Android 示例应用。每个 Activity 演示了 Rive Android 运行时的一个特定功能。
git clone https://github.com/rive-app/rive-android
在 Android Studio 中打开克隆的文件夹，选择 app 配置和目标设备。通过打开菜单 Build - Select Build Variant... 并选择 preview (default) 变体，确保构建变体设置为 preview (default)。
其他构建变体用于开发目的，需要额外配置。请参阅 CONTRIBUTING.MD。
入门
如果你在寻找旧版 API 的入门说明，请参阅 入门（旧版 API）。
将 Rive 添加到你的项目
添加 Rive 依赖
将以下依赖添加到你的项目 build.gradle 文件中。我们推荐使用最新版本的 Rive Android 运行时，可以在 Maven Central 上找到。
dependencies {
...
implementation 'app.rive:rive-android:<Latest Version>'
// 对于初始化，你可能需要添加 Jetpack Startup 依赖
implementation "androidx.startup:startup-runtime:1.1.1"
}
初始化 Rive
Rive 需要链接并初始化其 C++ 运行时，以便 Kotlin 绑定正常工作。
这可以通过一个 初始化器 来自动完成，该初始化器在应用程序启动时执行。初始化提供程序可以直接在你的应用的清单文件中设置。
<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>
或者，你也可以在代码中调用初始化器来实现。
AppInitializer.getInstance(applicationContext)
.initializeComponent(RiveInitializer::class.java)
如果你想自己初始化 Rive，可以在代码中使用以下方式。这是最灵活的选项，因为你可以延迟加载本地库，但请确保在使用任何 Rive 功能之前调用它。
Rive.init(context)
将 Rive 添加到你的布局
现在你可以将 Rive 可组合项添加到你的 Compose 布局中。请参阅以下部分了解详情。如果你使用的是旧版 API，请转而参阅 入门（旧版 API）。
启用日志记录
Compose API 使用大量日志记录，尤其是在调试级别，以帮助诊断问题。默认情况下未启用任何日志记录器。通常，你会希望将全局日志记录器设置为输出到 Android 的 Logcat，这可以通过以下便捷函数实现。这可以在你的 Activity 的 onCreate 方法或 Application 子类中完成，例如，在任何 Rive 功能使用之前。
RiveLog.logger = RiveLog.LogcatLogger()
将 Rive 添加到你的组合中
创建 Worker
Compose API 使用显式的 Rive worker，该 worker 拥有一个线程用于 Rive 操作，包括文件和资源解码、推进和绘制。在使用任何 API 之前，你必须创建一个 worker 来托管这些操作。请注意，worker 必须在其创建的所有 Rive 资源的生命周期内存在。
在 Compose 上下文中，最简单的 API 是 rememberRiveWorker，它会为组合的生命周期创建并记住一个 worker。但是，如果你希望在 worker 创建期间处理任何意外错误，可以使用 rememberRiveWorkerOrNull，如果无法创建 worker，它将返回 null 并将错误转发到你提供的错误状态。
setContent {
// 简单
val riveWorker = rememberRiveWorker()
// 安全
val errorState = remember { mutableStateOf<Throwable?>(null) }
val riveWorker = rememberRiveWorkerOrNull(errorState)
if (riveWorker == null) {
// 处理错误并提前返回
return@setContent
}
}
加载 Rive 文件
在显示 Rive 元素之前，你必须加载 Rive 文件，即导出的 .riv 文件。Rive 文 件由 RiveFileSource 指定，可以是 RawRes（用于本地原始资源）或 Bytes（用于来自任何来源（包括网络）的原始字节数据）。在这里，我们将使用原始资源以简化操作。该源以及上面的 worker 被传递给 rememberRiveFile，它会在内部加载并缓存文件以供组合使用。
setContent {
... // 来自上面的 riveWorker
val riveFile = rememberRiveFile(
RiveFileSource.RawRes.from(R.raw.my_rive_file),
riveWorker
)
}
返回的值是一个 Result<RiveFile>，可以是 Loading、Success 或 Error。这种模式要求你在 UI 中适当处理加载和错误状态。通常使用 when 语句来完成。
when (riveFile) {
is Result.Loading -> LoadingIndicator()
is Result.Error -> /* 处理错误 */
is Result.Success -> {
// `RiveFile` 保存在 `value` 属性中
val file = riveFile.value
// 使用文件 - 参见下一步
}
}
使用 Rive 可组合项
有了加载的 RiveFile，你现在可以使用 Rive 可组合项来显示它。worker 被捕获在 Rive 文件中，因此这两个组件就是所需的一切。如果未进一步指定，它将选择默认的画板和状态机（在 Rive 编辑器中指定）。其他选项将在其他文档部分中探讨，例如画板、状态机和数据绑定。
when (riveFile) {
...
is Result.Success -> {
Rive(riveFile.value)
}
}