Flutter 运行时（Flutter）

概览（Overview）

本页介绍如何在 Flutter 应用中集成 Rive。

说明（Note）：rive 最新版本目前以 0.14.0-dev.x 发布。该版本已可用于生产，但仍在持续迭代新功能，建议优先使用最新 dev 版本。

如果你已在使用旧版 Flutter Runtime，请先看：

• 迁移指南（Migration Guide）

快速示例：

• 官方 Example App：https://github.com/rive-app/rive-flutter/tree/master/example

快速上手（Getting Started）

1) 添加依赖

# pubspec.yaml
dependencies:
  rive: ^0.14.0-dev.6 # 或最新版本

2) 导入包

import 'package:rive/rive.dart';

避免命名冲突可使用别名：

import 'package:rive/rive.dart' as rive;

3) 初始化 RiveNative

建议在应用启动时调用：

import 'package:rive/rive.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await RiveNative.init();
  runApp(const MyApp());
}

4) 选择组件

当前推荐组合：

• RiveWidget：负责渲染
• RiveWidgetBuilder：负责加载/错误态/资源管理
• RivePanel：多图共享纹理（仅 Factory.rive）

方式 A：RiveWidgetBuilder（推荐）

late final fileLoader = FileLoader.fromAsset(
  "assets/vehicles.riv",
  riveFactory: Factory.rive,
);

@override
Widget build(BuildContext context) {
  return RiveWidgetBuilder(
    fileLoader: fileLoader,
    builder: (context, state) => switch (state) {
      RiveLoading() => const Center(child: CircularProgressIndicator()),
      RiveFailed() => Text(state.error.toString()),
      RiveLoaded() => RiveWidget(
          controller: state.controller,
          fit: Fit.cover,
        ),
    },
  );
}

方式 B：直接 RiveWidget

final file = await File.asset("assets/vehicles.riv", riveFactory: Factory.rive);
final controller = RiveWidgetController(file!);

RiveWidget(controller: controller, fit: Fit.cover)

方式 C：RivePanel（多实例性能优化）

当你在同一页面展示大量 Rive 图形时，可用 RivePanel 降低纹理开销：

• 外层包一层 RivePanel
• 每个 RiveWidget 开启 useSharedTexture: true
• 可用 drawOrder 控制绘制顺序

核心组件说明

RiveWidget

关键属性：

• controller（必填）
• fit / alignment
• layoutScaleFactor
• useSharedTexture
• drawOrder

RiveWidgetBuilder

关键属性：

• fileLoader（必填）
• builder（必填）
• artboardSelector
• stateMachineSelector
• dataBind
• onLoaded / onFailed

RiveWidgetController

final controller = RiveWidgetController(
  file,
  artboardSelector: ArtboardSelector.byName("MyArtboard"),
  stateMachineSelector: StateMachineSelector.byName("MyStateMachine"),
);

数据绑定示例：

controller.dataBind(DataBind.auto());
controller.dataBind(DataBind.byName("MyViewModel"));

文件加载（File Loading）

从 Asset

final fileLoader = FileLoader.fromAsset("assets/vehicles.riv", riveFactory: Factory.rive);

从 URL

final fileLoader = FileLoader.fromUrl("https://cdn.rive.app/animations/vehicles.riv", riveFactory: Factory.rive);

从已有 File

final fileLoader = FileLoader.fromFile(existingFile, riveFactory: Factory.rive);

渲染器选择（Renderer）

创建 File 或 FileLoader 时需指定：

• Factory.rive：Rive Renderer
• Factory.flutter：Flutter Renderer（Skia / Impeller）

注意：

• Vector Feathering 仅 Factory.rive 支持
• Linux 上目前会自动回退到 Factory.flutter

更多说明：

• Choose a Renderer

排障（Troubleshooting）

1. 确保先执行 await RiveNative.init()
2. 检查 pubspec.yaml 资源路径
3. RiveWidgetBuilder 中完整处理 loading/failed/loaded

常用清理命令：

flutter clean
flutter pub get
flutter run

如仍失败，可参考：

• Flutter FAQ
• Rive Native for Flutter

资源（Resources）

• Rive Flutter GitHub：https://github.com/rive-app/rive-flutter
• pub.dev（rive）：https://pub.dev/packages/rive
• Example App：https://github.com/rive-app/rive-flutter/tree/master/example/
• rive_native（pub.dev）：https://pub.dev/packages/rive_native