跳到主要内容

Flutter 运行时（Flutter）

概览（Overview）​

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

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

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

快速示例：

快速上手（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

更多说明：

排障（Troubleshooting）​

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

常用清理命令：

flutter clean
flutter pub get
flutter run

如仍失败，可参考：

资源（Resources）​