迁移指南

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

⚠️ 警告：包含重大变更

Rive 渲染器

RendererType

riveRenderer 现在是新的默认渲染器类型，skiaRenderer 已被移除。如果你之前显式地将渲染器类型设置为 Skia，那么你需要指定新的渲染器，或使用新的默认 Rive 渲染器（我们推荐）。

包大小

Rive 的 iOS 运行时现在缩小了约 57%，约为 3.3MB，而 v6.0.0 之前约为 7.6MB。

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

没有重大 API 变更！

迁移到 v5.x.x 应该不需要对代码进行重大更改。从 v5.x.x 开始，新增了一个文本引擎依赖以支持 Rive 文本功能，因此你可能会看到包大小略有增加。

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

迁移到 v4.x.x 应该不需要对代码进行重大更改。从 v4.0.1 开始，你可以使用相同的运行时包 rive-ios 将 RiveRuntime 安装到原生 macOS 应用中。RiveRuntime 在 iOS 和 macOS 应用中的 API 使用应保持一致。如果你发现任何差异或问题，请在 https://github.com/rive-app/rive-ios/issues 提交 issue。

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

迁移到 Apple 运行时的 v3 应该相当简单。请参见以下部分，了解升级时可能需要关注的问题。

枚举命名

从 v3 开始，布局选项枚举已更改，以匹配其他运行时的枚举命名约定，保持一致性。请参见以下内容，了解 Fit 和 Alignment 选项应更改为何值。还有一些其他参数的枚举在循环模式和方向方面略有变化。

Fit	之前	之后
Fill	`.fitFill`	`.fill`
Contain	`.fitContain`	`.contain`
Cover	`.fitCover`	`.cover`
Fit Width	`.fitFitWidth`	`.fitWidth`
Fit Height	`.fitFitHeight`	`.fitHeight`
Scale Down	`.fitScaleDown`	`.scaleDown`
None	`.fitNone`	`.noFit`

Alignment	之前	之后
Top Left	`.alignmentTopLeft`	`.topLeft`
Top Center	`.alignmentTopCenter`	`.topCenter`
Top Right	`.alignmentTopRight`	`.topRight`
Center Left	`.alignmentCenterLeft`	`.centerLeft`
Center	`.alignmentCenter`	`.center`
Center Right	`.alignmentCenterRight`	`.centerRight`
Bottom Left	`.alignmentBottomLeft`	`.bottomLeft`
Bottom Center	`.alignmentBottomCenter`	`.bottomCenter`
Bottom Right	`.alignmentBottomRight`	`.bottomRight`

Loop Mode	之前	之后
One Shot	`loopOneShot`	`oneShot`
Loop	`loopLoop`	`loop`
Ping Pong	`loopPingPong`	`pingPong`
Auto	`loopAuto`	`autoLoop`

Direction	之前	之后
Backwards	`directionBackwards`	`backwards`
Forwards	`directionForwards`	`forwards`
Auto	`directionAuto`	`autoDirection`

默认播放行为

v3 中一个更改的默认行为是 Rive 画布中播放的内容。在 v3 之前，如果设置 RiveViewModel 时没有指定状态机或特定动画，将播放 Rive 文件中创建的第一个动画。

在 v3 中，如果没有指定状态机或特定动画，将播放 Rive 文件中的第一个状态机（如果已创建）。因此，如果你希望保留现有的默认行为（播放第一个动画），只需在创建 RiveViewModel 时设置 animationName 属性。

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

Rive Apple 运行时在 2.x.x 中具有与 1.x.x 不同的 API，允许使用统一的内部模型来支持 Storyboard/UIKit 和 SwiftUI 使用。

现在 iOS 开发需要熟悉的 Rive API 主要有 3 个部分：

RiveView - 构建和操作 Rive 视图的核心逻辑
RiveModel - 描述 Rive 对象的配置模型
RiveViewModel - 集成 Rive 时的主要接口类，在某些情况下创建 Rive 视图。它提供高级 API，使实例化、动画播放、布局更改等操作变得简单。

我们建议尽快迁移到最新版本的 v2.x.x，你可以在下面找到相关步骤：

UIKit

在 v1.x.x 中，你可能使用以下代码片段模式加载 Rive 文件：

class SimpleAnimationViewController: UIViewController {
    let url = "https://cdn.rive.app/animations/truck.riv"

    override public func loadView() {
        super.loadView()

        let view = RiveView()
        guard let riveFile = RiveFile(httpUrl: url, with: view) else {
            fatalError("Unable to load RiveFile")
        }
        try? view.configure(riveFile)

        self.view = view
    }
}

此模式与 2 个 Rive API 交互：RiveFile 和 RiveView。在 v2.x.x 中，模式变得更简单，只需与一个 RiveViewModel 交互。

class SimpleAnimationViewController: UIViewController {
    var viewModel = RiveViewModel(fileName: "truck")

    override func viewWillAppear(_ animated: Bool) {
        let riveView = viewModel.createRiveView()
        view.addSubview(riveView)
        riveView.frame = view.frame
    }
}

另一个示例：

class MultipleAnimationsController: UIViewController, RivePlayerDelegate {
    @IBOutlet weak var riveView: RiveView!

    var viewModel = RiveViewModel(
        fileName: "multiple_animations",
        animationName: "Animation 1",
        artboardName: "Animation Playground"
    )

    override func viewDidLoad() {
        viewModel.setView(riveView)
    }
}

请参阅后续运行时页面，了解 UIKit 中动画播放和布局的新用法。

状态机使用

在 v1.x.x 中，你使用以下 API 设置状态机输入值：

riveView.setNumberState("Number Test", inputName: "Level", value: 2.0)

riveView.setBooleanState("Boolean Test", inputName: "isSuccess", value: true)

riveView.fireState("Trigger Test", inputName: "trigFail")

在 v2.x.x 中，一些输入状态设置器已合并和重命名。此外，设置器在 RiveViewModel 上调用，该对象具有实例化的状态机上下文，因此不再需要传递名称：

viewModel.setInput("Level", value: 2.0)

viewModel.setInput("isSuccess", value: true)

viewModel.triggerInput("trigFail")

代理

过去，你可能实现了来自以下代理的各种函数：LoopDelegate、PlayDelegate、PauseDelegate、StopDelegate 和 StateChangeDelegate。在你的端实现的各种函数（例如 loop、play、pause、stateChange 等）已合并为 2 个主要代理：RivePlayerDelegate 和 RiveStateMachineDelegate，具有略有不同的重写函数。

请参见以下代理列表，了解可挂钩的方法：

RivePlayerDelegate - 挂钩动画和状态机生命周期事件
- player: (loopedWithModel riveModel: RiveModel?, type: Int) {}
- player: (playedWithModel riveModel: RiveModel?) {}
- player: (pausedWithModel riveModel: RiveModel?) {}
- player: (stoppedWithModel riveModel: RiveModel?) {}
RiveStateDelegate - 挂钩状态机生命周期的状态更改
- stateChange: (_ stateMachineName: String, _ stateName: String) {}

SwiftUI

v1.x.x 在现有 RiveView 类周围有一个小包装器，以帮助在用 SwiftUI 编写的应用上下文中支持 Rive。v2.x.x 现在支持更强大的模式，用于在 SwiftUI 应用中消费 Rive，修复了现有包装器方法的几个错误，并提供了与 SwiftUI 新模式更接近的体验。

请参阅后续运行时页面，了解如何在 v2.x.x 中控制动画播放、状态机等。

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

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

Rive 渲染器​

RendererType​

包大小​

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

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

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

枚举命名​

默认播放行为​

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

UIKit​

状态机使用​

代理​

SwiftUI​