跳到主要内容
中文系列课

迁移指南（Migration Guides）

从 5.x.x 迁移到 6.x.x​

警告（Warning）：包含破坏性变更。

RendererType 变化​

  • riveRenderer 现在是默认渲染器
  • skiaRenderer 已移除

如果你之前显式设置 Skia，请改为选择新的渲染器策略（推荐直接使用默认 Rive Renderer）：

包体积变化​

官方说明 iOS runtime 大小约从 ~7.6mb 降到 ~3.3mb（约 57%）。

从 4.x.x 迁移到 5.x.x​

说明（Note）：无破坏性 API 变更。

迁移到 v5.x.x 一般无需大改。v5 引入了文本引擎依赖以支持 Text 能力，因此包体积可能略有增加。

从 3.x.x 迁移到 4.x.x​

通常无需大改。自 v4.0.1 起，rive-ios 可用于原生 macOS 应用安装 RiveRuntime。

如遇问题可反馈：

从 2.x.x 迁移到 3.x.x​

枚举命名调整​

为与其他 runtime 一致，v3 调整了若干枚举命名（尤其是 Layout 相关）。

Fit​

  • .fitFill → .fill
  • .fitContain → .contain
  • .fitCover → .cover
  • .fitFitWidth → .fitWidth
  • .fitFitHeight → .fitHeight
  • .fitScaleDown → .scaleDown
  • .fitNone → .noFit

Alignment​

  • .alignmentTopLeft → .topLeft
  • .alignmentTopCenter → .topCenter
  • .alignmentTopRight → .topRight
  • .alignmentCenterLeft → .centerLeft
  • .alignmentCenter → .center
  • .alignmentCenterRight → .centerRight
  • .alignmentBottomLeft → .bottomLeft
  • .alignmentBottomCenter → .bottomCenter
  • .alignmentBottomRight → .bottomRight

Loop Mode​

  • loopOneShot → oneShot
  • loopLoop → loop
  • loopPingPong → pingPong
  • loopAuto → autoLoop

Direction​

  • directionBackwards → backwards
  • directionForwards → forwards
  • directionAuto → autoDirection

默认播放行为变化​

v3 起，若未指定状态机或动画：

  • 旧行为：播放文件中的第一条动画
  • 新行为：优先播放第一条状态机（若存在）

若你要保持旧行为，请在 RiveViewModel 初始化时显式设置 animationName。

从 1.x.x 迁移到 2.x.x​

v2 的 Apple API 与 v1 差异较大，目标是统一 UIKit/Storyboard/SwiftUI 的内部模型。

v2 的三个核心对象​

  • RiveView
  • RiveModel
  • RiveViewModel（主要对接对象）

UIKit 迁移方向​

v1 常见是 RiveFile + RiveView 组合，v2 建议直接面向 RiveViewModel。

State Machine Inputs 变化​

旧 API：setNumberState / setBooleanState / fireState

v2 改为 RiveViewModel 上统一输入接口，例如：

  • setInput("Level", value: 2.0)
  • setInput("isSuccess", value: true)
  • triggerInput("trigFail")

Delegate 收敛​

旧版多组 Delegate（Loop/Play/Pause/Stop/StateChange）被收敛为：

  • RivePlayerDelegate
  • RiveStateMachineDelegate

SwiftUI 支持增强​

v2 提供更稳健的 SwiftUI 集成方式，修复了 v1 包装层方案中的一些问题。

可直接：

struct AnimationView: View {
    var body: some View {
        RiveViewModel(fileName: "cool_rive_animation").view()
    }
}