Flutter 版 Rive Native

一个 Flutter 插件，集成了 Rive 渲染器和核心 Rive C++ 运行时。由 Rive Flutter 运行时使用。

Rive Native 与 Rive 的区别

Rive Native（rive_native）是一个 Flutter 插件，集成了 Rive 渲染器和核心 Rive C++ 运行时。

Rive Flutter 运行时（rive）构建在 rive_native 之上。我们建议将 rive 包作为依赖项包含，因为它会自动包含 rive_native，同时还提供了在 Flutter 中处理 Rive 资源的用户友好 API。

Rive Native 取代了 Rive Flutter 之前用于原生操作的 Rive Common（rive_common）插件。

理解 Rive Native

Rive Native 充当 Flutter 与 Rive C++ 运行时之间的桥梁，允许你在 Flutter 应用中使用 Rive 图形。

C++ 运行时集成： rive_native 通过 FFI 基于 Rive 的 C++ 运行时构建。这确保了跨平台和 Rive 编辑器的一致体验，同时解锁了 C++ 运行时独有的性能改进和新功能，例如：
Rive 渲染器支持： rive_native 将 Rive 渲染器带入 Flutter。虽然你仍然可以使用基于 Flutter 的渲染器（Dart/Impeller），但对于性能关键的使用场景，建议使用 Rive 渲染器。更多信息请参见选择渲染器。

某些功能（如矢量羽化）仅在 Rive 渲染器下受支持。详情请参见功能支持页面。

入门指南

rive_native 目前尚未在 GitHub 上公开发布，但即将发布。目前，你可以通过运行以下命令拉取源代码和示例：

dart pub unpack rive_native # 解压包源代码和示例应用
cd rive_native/example      # 导航到示例文件夹
flutter create .            # 创建平台文件夹
flutter pub get             # 获取依赖
flutter run                 # 运行示例应用

有关示例实现，请参见 rive_native/example/rive_player.dart 中的 rive_player.dart 文件。

平台支持

平台	Flutter 渲染器	Rive 渲染器
iOS	✅	✅
Android	✅	✅
macOS	✅	✅
Windows	✅	✅
Linux	✅	✅
Web	✅	✅

预构建的 Linux 库尚不包含 arm64。在 Linux arm64 上，请手动构建 rive_native。

功能支持

详情请参见功能支持页面。

故障排查

所需的原生库应在构建步骤（flutter run 或 flutter build）中自动下载。如果遇到问题，请尝试以下步骤：

运行 flutter clean
运行 flutter pub get
运行 flutter run

或者，你可以手动运行 rive_native 设置脚本。在 Flutter 应用的根目录中执行：

dart run rive_native:setup --verbose --clean --platform macos

这将清除 rive_native 设置并下载由 --platform 标志指定的平台特定库。请参阅上文的平台支持部分了解详情。

Android

如果你遇到自动化设置问题（示例问题 555 和 515），可以通过在应用的 gradle.properties 中设置 rive.native.skipSetup=true 来跳过设置。

启用后，你必须手动运行 dart run rive_native:setup --verbose --clean --platform android 来下载所需的库。

构建 `rive_native`

默认情况下，会下载并使用预构建的原生库。你也可以从源码构建：已发布的 rive_native 包包含完整的 C++ 源码（native/ 和 runtime/），设置脚本会在 Pub 缓存中就地编译。

查看你平台的构建要求，然后在 Flutter 应用的根目录中运行以下命令：

flutter clean # 重要
flutter pub get # 设置需要 .dart_tool/package_config.json
dart run rive_native:setup --verbose --clean --build --platform macos

--platform 接受 android、ios、macos、windows 和 linux，或逗号分隔的列表（例如 android,macos）。除 Android 外，每个平台都必须在其目标操作系统上构建；Android 可以在任何主机上构建并生成所有四个 ABI（armeabi-v7a、arm64-v8a、x86、x86_64）。对于 Web，请参见下方的 Web 部分。

成功构建后，包中会留下一个 rive_marker_<platform>_development 文件，因此后续的 flutter run 和 flutter build 调用会使用你本地构建的库而非下载预构建库。如果不使用 --clean，一旦此标记存在，设置脚本不会执行任何操作。

构建要求（Build Requirements）

所有平台：

网络访问和 git：首次构建会从公共 GitHub 仓库克隆构建系统和第三方源码（HarfBuzz、Yoga、zlib 等）到包的 native/dependencies/ 文件夹——无需凭据。
bash、GNU make 和 python3：构建脚本和着色器生成使用。

各平台要求：

macOS / iOS：Xcode
Android：Android NDK r27c（27.2.12479018）——强制要求确切版本；将 NDK_PATH 或 ANDROID_NDK 指向它——以及 ninja。
Windows：Visual Studio 2022（使用 C++ 的桌面开发工作负载），msbuild.exe 在 PATH 中（例如从 Visual Studio 开发者提示符运行），Git Bash 和 make（choco install make）。
Linux：clang、cmake、ninja-build、pkg-config、libgtk-3-dev、uuid-dev、libstdc++-12-dev 和 libvulkan-dev（apt 包名）。

回退到预构建库（Returning to Prebuilt Libraries）

不带 --build 运行设置脚本——--clean 移除已构建的库和标记文件，预构建库会再次下载：

dart run rive_native:setup --verbose --clean --platform macos
flutter clean

由于下载和本地构建的库都位于 Pub 缓存中，dart pub cache repair 和 dart pub cache clean 也会移除它们。它们会在下次 flutter run 时恢复，或通过重新运行设置脚本恢复。

Web

设置脚本不管理 Web 二进制文件。在 Web 上，rive_native 在运行时从 Rive 的 CDN（jsDelivr，固定为与包版本匹配的版本）加载其 WebAssembly 模块。

要自行托管这些文件，请从 @rive-app/flutter-native-wasm NPM 包中复制 wasm/ 和 wasm_compatibility/ 文件夹到你的服务器，然后使用以下命令构建：

flutter run --dart-define=RIVE_NATIVE_WASM_HOST=https://your-host/your-path/

末尾的斜杠是必需的——运行时会将 wasm/rive_native.js 或 wasm_compatibility/rive_native.js 追加到主机 URL。

测试

共享库包含在下载/构建过程中。如果你在测试中使用 rive_native 时遇到问题，请联系我们获取帮助。

看完还有疑问？进群交流下！

与众多 Rive 创作者、开发者一起交流探讨与答疑解惑。

加入交流群

Rive Native 与 Rive 的区别​

理解 Rive Native​

入门指南​

平台支持​

功能支持​

故障排查​

Android​

构建 rive_native​

构建要求（Build Requirements）​

回退到预构建库（Returning to Prebuilt Libraries）​

Web​

测试​