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、GNUmake和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 时遇到问题，请联系我们获取帮助。