将 Flutter 集成到现有应用

集成到现有应用

Add-to-app

有时候,用 Flutter 一次性重写整个已有的应用是不切实际的。对于这些情况,Flutter 可以作为一个库或模块,集成进现有的应用当中。模块引入到您的 Android 或 iOS 应用(当前支持的平台)中,以使用 Flutter 来渲染一部分的 UI,或者仅运行多平台共享的 Dart 代码逻辑。

It’s sometimes not practical to rewrite your entire application in Flutter all at once. For those situations, Flutter can be integrated into your existing application piecemeal, as a library or module. That module can then be imported into your Android or iOS (currently supported platforms) app to render a part of your app’s UI in Flutter. Or, just to run shared Dart logic.

仅需几步,你就可以将高效而富有表现力的 Flutter 引入您的应用。

In a few steps, you can bring the productivity and the expressiveness of Flutter into your own app.

在 Flutter v1.12 中,添加到现有应用的基本场景已被支持,每个应用在同一时间可以集成一个全屏幕的 Flutter 实例。目前仍有以下限制:

As of Flutter v1.12, add-to-app is supported for the basic scenario of integrating one full-screen Flutter instance at a time per app. It currently has the following limitations:

  • 目前尚未支持将多个 Flutter 库打包到同一个应用中;

    Packing multiple Flutter libraries into an application isn’t supported.

  • 在 Android 平台,使用了添加到现有应用 (add-to-app) 的插件需要迁移到基于 FlutterPluginAndroid 插件 API

    Plugins used in add-to-app on Android should migrate to the new Android plugin APIs, based on FlutterPlugin.

  • 一些不支持 FlutterPlugin 的插件可能会有不可预知的行为,比如产生错误的预判,认为 Flutter Activity 一直处于活跃状态。

    Plugins that don’t support FlutterPlugin might have unexpected behaviors if they make assumptions that are untenable in add-to-app (such as assuming that a Flutter Activity is always present).

  • 从 1.17 开始,Flutter 模块仅支持 Android 平台中的 AndroidX 应用。

    As of v1.17, the Flutter module only supports AndroidX applications on Android.

自 Flutter 1.26 版本开始,add-to-app 开始实验性的支持将多个 Flutter 引擎 (engine)、页面 (screen) 或视图 (view) 添加到你的应用中。适用于混合栈应用在导航到原生页面和 Flutter 页面的情况,也适用于一个页面有原生视图和 Flutter 视图的情况等混合栈应用。多个 Flutter 实例会帮助每个实例保持独立的应用和 UI 状态,同时使用最少的内存资源。请多详细内容,请参考文档: 多个 Flutter 实例

As of Flutter v1.26, add-to-app experimentally supports adding multiple instances of Flutter engines, screens, or views into your app. This can help integration scenarios such as a hybrid navigation stack with mixed native and Flutter screens, or a page with multiple partial-screen Flutter views. Having multiple Flutter instances allows each instance to maintain independent application and UI state while using minimal memory resources. See more in the multiple Flutters page.

已支持的特性

Supported features

集成到 Android 应用

Add to Android applications

Add-to-app steps on Android
  • 在 Gradle 脚本中添加一个自动构建并引入 Flutter 模块的 Flutter SDK 钩子。

    Auto-build and import the Flutter module by adding a Flutter SDK hook to your Gradle script.

  • 将 Flutter 模块构建为通用的 Android Archive (AAR) 以便集成到您自己的构建系统中,并提高 Jetifier 与 AndroidX 的互操作性;

    Build your Flutter module into a generic Android Archive (AAR) for integration into your own build system and for better Jetifier interoperability with AndroidX.

  • FlutterEngine API 用于启动并持续地为挂载 FlutterActivityFlutterFragment 提供独立的 Flutter 环境;

    FlutterEngine API for starting and persisting your Flutter environment independently of attaching a FlutterActivity/FlutterFragment etc.

  • Android Studio 的 Android 与 Flutter 同时编辑,以及 Flutter module 创建与导入向导;

    Android Studio Android/Flutter co-editing and module creation/import wizard.

  • 支持了 Java 和 Kotlin 为宿主的应用程序;

    Java and Kotlin host apps are supported.

  • Flutter 模块可以通过使用 Flutter plugins 与平台进行交互。 Android 平台的 plugin 应该 迁移至 V2 plugin API 以确保最佳的兼容性。在 Flutter v1.12,大多数 Flutter 团队维护 的 plugin,以及 FlutterFire 都已完成迁移;

    Flutter modules can use Flutter plugins to interact with the platform. Android plugins should be migrated to the V2 plugins APIs for best add-to-app correctness. As of Flutter v1.12, most of the plugins maintained by the Flutter team as well as FlutterFire have been migrated.

  • 支持通过从 IDE 或命令行中使用 flutter attach 来实现 Flutter 调试与有状态的热重载。

    Support for Flutter debugging and stateful hot reload by using flutter attach from IDEs or the command line to connect to an app that contains Flutter.

集成到 iOS 应用

Add to iOS applications

Add-to-app steps on iOS
  • 在 Xcode 的 Build Phase 以及 CocoaPods 中,添加一个自动构建并引入 Flutter 模块的 Flutter SDK 钩子。

    Auto-build and import the Flutter module by adding a Flutter SDK hook to your CocoaPods and to your Xcode build phase.

  • 将 Flutter 模块构建为通用的 iOS Framework 以便集成到您自己的构建系统中;

    Build your Flutter module into a generic iOS Framework for integration into your own build system.

  • FlutterEngine API 用于启动并持续地为挂载 FlutterViewController 以提供独立的 Flutter 环境;

    FlutterEngine API for starting and persisting your Flutter environment independently of attaching a FlutterViewController.

  • 支持了 Objective-C 和 Swift 为宿主的应用程序;

    Objective-C and Swift host apps supported.

  • Flutter 模块可以通过使用 Flutter plugins 与平台进行交互;

    Flutter modules can use Flutter plugins to interact with the platform.

  • 支持通过从 IDE 或命令行中使用 flutter attach 来实现 Flutter 调试与有状态的热重载。

    Support for Flutter debugging and stateful hot reload by using flutter attach from IDEs or the command line to connect to an app that contains Flutter.

查看 add-to-app GitHub 示例仓库 中在 iOS 和 Android 平台上引入 Flutter module 的示例项目。

See our add-to-app GitHub Samples repository for sample projects in Android and iOS that import a Flutter module for UI.

开始

Get started

第一步,查看以下工程集成指南

To get started, see our project integration guide for Android and iOS:

API 用法

API usage

将 Flutter 集成进您的工程后,可以查看以下 API 使用指南

After Flutter is integrated into your project, see our API usage guides at the following links: