从 Legacy 迁移（Migrating from Legacy）

概览（Overview）

新版 Android Runtime 是对公开 API 与内部架构的近乎重写版本。

虽然大多数能力在概念上可对应，但两套 API 并不兼容。若你要迁移 Legacy 项目，需要按新版方式重建集成。

本页给出迁移主线与关键映射，完整细节可结合官方原文：

• /docs/Runtimes/Android/Migrating from Legacy

本指南覆盖内容

1. 共享特性（Shared Features）：新旧 API 对应关系
2. 新版独有特性（New Exclusive Features）：仅新版支持
3. 旧版独有特性（Legacy Exclusive Features）：新版不再支持与替代方案

说明（Note）：本页为中文迁移导航版，后续我会按章节继续补全所有示例与对照代码。

迁移关键结论（先看这个）

1) 包名变化

• Legacy：app.rive.runtime.kotlin（及 .core）
• New：app.rive（及 .core）

必要时可用 Kotlin import as 解决重名类。

2) 同步 API 变异步

由于新版基于 RiveWorker 的线程模型，很多旧版主线程同步操作已变为异步 suspend。

常见做法：

• Compose 中用 rememberRiveFile
• 或在 LaunchedEffect / lifecycleScope.launch 中调用

3) 生命周期管理变化

• Legacy 依赖 RiveAnimationView 与 Activity/Fragment 生命周期
• New 使用 AutoCloseable + Worker 管理资源

手动创建对象时需及时 close 或用 use 块释放。

4) UI 入口变化

• Legacy：RiveAnimationView（View/XML）
• New：Rive(...)（Compose）

未来官方计划补 View API，但当前主路线是 Compose。

典型迁移映射（简表）

• setRiveResource(...) / XML app:riveResource
  → rememberRiveFile(RiveFileSource.RawRes...)

• setArtboardName / setStateMachineName
  → rememberArtboard(...) + rememberStateMachine(...) 后传给 Rive(...)

• setFit + setAlignment
  → Rive(..., fit = Fit.Contain(Alignment.Center))

• play() / pause()
  → Rive(..., playing = state)

• Legacy autoplay
  → 默认 playing = true；若需先改初始值，先 playing=false，设置后再 true

• State Machine Inputs / Events / Text Runs（Legacy 方案）
  → 推荐迁移到 Data Binding（ViewModel 属性）

新版独有亮点（摘要）

• 更完整日志能力（Logging）
• 渲染到 Bitmap（Rendering to Bitmap）
• 数据绑定更新后自动触发状态机“unsettle”

旧版独有但新版未覆盖（摘要）

• 旧版 View API（未来计划补）
• 旧版内置 CDN Assets 与 URL 直连加载（新版建议自行网络层 + Bytes source）
• 旧版 Canvas Renderer（新版聚焦 Rive Renderer）
• 直接线性动画播放、多状态机同实例等能力（建议迁移到状态机/数据绑定语义）

建议迁移顺序

1. 先迁移文件加载与渲染容器（RiveAnimationView → Rive）
2. 再迁移布局、Artboard、State Machine 选择
3. 最后迁移交互与数据层（Inputs/Events/Text Runs → Data Binding）

参考链接

• Android Runtime：/docs/Runtimes/Android/Android
• Legacy 入门：/docs/Runtimes/Android/Getting Started (Legacy API)
• 官方迁移文档：/docs/Runtimes/Android/Migrating from Legacy